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

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

@@ -0,0 +1,141 @@
+/**
+ * LSPTool — language server protocol operations for code intelligence.
+ */
+import { getLSPManager } from "../../lsp/manager.js";
+import { detectLSPServer } from "../../lsp/servers.js";
+import { pathToFileURL } from "node:url";
+export const lspToolDef = {
+    name: "LSP",
+    description: "Use Language Server Protocol for code intelligence operations. " +
+        "Available actions: goToDefinition, findReferences, hover, getDiagnostics, getSymbols. " +
+        "Requires a language server to be installed for the target language.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["goToDefinition", "findReferences", "hover", "getDiagnostics", "getSymbols"],
+                description: "The LSP operation to perform",
+            },
+            file_path: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            line: {
+                type: "number",
+                description: "Line number (0-based). Required for goToDefinition, findReferences, hover.",
+            },
+            character: {
+                type: "number",
+                description: "Character offset (0-based). Required for goToDefinition, findReferences, hover.",
+            },
+        },
+        required: ["action", "file_path"],
+    },
+};
+export async function lspTool(args) {
+    const action = args.action;
+    const filePath = args.file_path;
+    const line = args.line ?? 0;
+    const character = args.character ?? 0;
+    if (!filePath)
+        return "Error: file_path is required";
+    const manager = getLSPManager();
+    if (!manager)
+        return "Error: LSP is not initialized. Language servers are not available.";
+    // Detect the appropriate server
+    const serverConfig = detectLSPServer(filePath);
+    if (!serverConfig)
+        return `Error: No language server configured for ${filePath}`;
+    const client = await manager.getClient(serverConfig.name);
+    if (!client) {
+        return `Error: Language server "${serverConfig.name}" is not available. Install: ${serverConfig.installHint}`;
+    }
+    const uri = pathToFileURL(filePath).href;
+    const position = { line, character };
+    try {
+        switch (action) {
+            case "goToDefinition": {
+                const result = await client.request("textDocument/definition", {
+                    textDocument: { uri },
+                    position,
+                });
+                return formatLocationResult(result, "Definition");
+            }
+            case "findReferences": {
+                const result = await client.request("textDocument/references", {
+                    textDocument: { uri },
+                    position,
+                    context: { includeDeclaration: true },
+                });
+                return formatLocationResult(result, "References");
+            }
+            case "hover": {
+                const result = await client.request("textDocument/hover", {
+                    textDocument: { uri },
+                    position,
+                });
+                if (!result)
+                    return "No hover information available.";
+                const content = typeof result.contents === "string"
+                    ? result.contents
+                    : result.contents?.value ?? JSON.stringify(result.contents);
+                return `Hover:\n${content}`;
+            }
+            case "getDiagnostics": {
+                // Open the document to trigger diagnostics
+                const { readFileSync } = await import("node:fs");
+                const text = readFileSync(filePath, "utf-8");
+                await client.notify("textDocument/didOpen", {
+                    textDocument: { uri, languageId: serverConfig.language, version: 1, text },
+                });
+                // Wait briefly for diagnostics
+                await new Promise((r) => setTimeout(r, 2000));
+                return "Diagnostics requested. Check LSP notifications for results.";
+            }
+            case "getSymbols": {
+                const result = await client.request("textDocument/documentSymbol", {
+                    textDocument: { uri },
+                });
+                if (!result?.length)
+                    return "No symbols found.";
+                const lines = result.map((s) => {
+                    const kind = SYMBOL_KINDS[s.kind] ?? `kind:${s.kind}`;
+                    const range = s.range ?? s.location?.range;
+                    const loc = range ? `:${range.start.line + 1}` : "";
+                    return `  ${kind} ${s.name}${loc}`;
+                });
+                return `Symbols in ${filePath}:\n${lines.join("\n")}`;
+            }
+            default:
+                return `Unknown action: ${action}`;
+        }
+    }
+    catch (err) {
+        return `LSP error: ${err.message}`;
+    }
+}
+function formatLocationResult(result, label) {
+    if (!result)
+        return `No ${label.toLowerCase()} found.`;
+    const locations = Array.isArray(result) ? result : [result];
+    if (locations.length === 0)
+        return `No ${label.toLowerCase()} found.`;
+    const lines = locations.map((loc) => {
+        const uri = loc.uri ?? loc.targetUri ?? "";
+        const range = loc.range ?? loc.targetRange ?? {};
+        const path = uri.replace("file://", "");
+        const line = (range.start?.line ?? 0) + 1;
+        return `  ${path}:${line}`;
+    });
+    return `${label} (${locations.length}):\n${lines.join("\n")}`;
+}
+const SYMBOL_KINDS = {
+    1: "File", 2: "Module", 3: "Namespace", 4: "Package",
+    5: "Class", 6: "Method", 7: "Property", 8: "Field",
+    9: "Constructor", 10: "Enum", 11: "Interface", 12: "Function",
+    13: "Variable", 14: "Constant", 15: "String", 16: "Number",
+    17: "Boolean", 18: "Array", 19: "Object", 20: "Key",
+    21: "Null", 22: "EnumMember", 23: "Struct", 24: "Event",
+    25: "Operator", 26: "TypeParameter",
+};

package/dist/tool-system/builtin/mcp-tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP (Model Context Protocol) tools — list, read, and auth for MCP resources.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const mcpToolDef: ToolDefinition;
+export declare function mcpToolExecute(args: Record<string, unknown>): Promise<string>;
+export declare const listMcpResourcesToolDef: ToolDefinition;
+export declare function listMcpResourcesTool(args: Record<string, unknown>): Promise<string>;
+export declare const readMcpResourceToolDef: ToolDefinition;
+export declare function readMcpResourceTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/mcp-tools.js

@@ -0,0 +1,102 @@
+/**
+ * MCP (Model Context Protocol) tools — list, read, and auth for MCP resources.
+ */
+// ─── MCPTool — invoke an MCP tool on a connected server ─────────
+export const mcpToolDef = {
+    name: "MCPTool",
+    description: "Call a tool provided by a connected MCP server. The tool name should include the server prefix.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            server: {
+                type: "string",
+                description: "The MCP server name to call the tool on",
+            },
+            tool: {
+                type: "string",
+                description: "The tool name to invoke",
+            },
+            arguments: {
+                type: "object",
+                description: "Arguments to pass to the tool",
+            },
+        },
+        required: ["server", "tool"],
+    },
+};
+export async function mcpToolExecute(args) {
+    const server = args.server;
+    const tool = args.tool;
+    const toolArgs = args.arguments ?? {};
+    try {
+        const { MCPManager } = await import("../mcp-manager.js");
+        const manager = MCPManager.getInstance();
+        const result = await manager.callTool(server, tool, toolArgs);
+        return typeof result === "string" ? result : JSON.stringify(result, null, 2);
+    }
+    catch (err) {
+        return `MCP tool error: ${err.message}`;
+    }
+}
+// ─── ListMcpResources — list available MCP resources ────────────
+export const listMcpResourcesToolDef = {
+    name: "ListMcpResources",
+    description: "List available resources from connected MCP servers.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            server: {
+                type: "string",
+                description: "Optional: filter by MCP server name. If omitted, lists all.",
+            },
+        },
+    },
+};
+export async function listMcpResourcesTool(args) {
+    const server = args.server ?? "";
+    try {
+        const { MCPManager } = await import("../mcp-manager.js");
+        const manager = MCPManager.getInstance();
+        const resources = await manager.listResources(server || undefined);
+        if (!resources || resources.length === 0) {
+            return "No MCP resources available.";
+        }
+        const lines = resources.map((r) => `  ${r.uri ?? r.name} — ${r.description ?? ""}`);
+        return `MCP Resources (${resources.length}):\n${lines.join("\n")}`;
+    }
+    catch (err) {
+        return `Error listing MCP resources: ${err.message}`;
+    }
+}
+// ─── ReadMcpResource — read a specific MCP resource ─────────────
+export const readMcpResourceToolDef = {
+    name: "ReadMcpResource",
+    description: "Read the content of an MCP resource by its URI.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            server: {
+                type: "string",
+                description: "The MCP server name providing the resource",
+            },
+            uri: {
+                type: "string",
+                description: "The URI of the resource to read",
+            },
+        },
+        required: ["server", "uri"],
+    },
+};
+export async function readMcpResourceTool(args) {
+    const server = args.server;
+    const uri = args.uri;
+    try {
+        const { MCPManager } = await import("../mcp-manager.js");
+        const manager = MCPManager.getInstance();
+        const content = await manager.readResource(server, uri);
+        return typeof content === "string" ? content : JSON.stringify(content, null, 2);
+    }
+    catch (err) {
+        return `Error reading MCP resource: ${err.message}`;
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Built-in memory tools — let the LLM list / read / save / delete persistent
+ * memory entries via schema-validated tool calls (no JSON-in-text parsing).
+ *
+ * Two scopes are exposed:
+ *   - "user"   Entries the user owns. Save / Delete here is permission-gated
+ *              (permissionDefault: "ask" set in the registry) so the user
+ *              confirms each modification. Reading is always free.
+ *   - "dream"  The auto-consolidation workspace. Save / Delete go through
+ *              with no prompt — this is the LLM's scratch area for the
+ *              auto-dream pipeline (and also reachable in normal sessions
+ *              when the user asks to clean it up).
+ *
+ * Delete is SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
+ * by MemoryManager, so accidental deletions are recoverable by hand.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const memoryListToolDef: ToolDefinition;
+export declare function memoryListTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const memoryReadToolDef: ToolDefinition;
+export declare function memoryReadTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const memorySaveToolDef: ToolDefinition;
+export declare function memorySaveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const memoryDeleteToolDef: ToolDefinition;
+export declare function memoryDeleteTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -0,0 +1,226 @@
+/**
+ * Built-in memory tools — let the LLM list / read / save / delete persistent
+ * memory entries via schema-validated tool calls (no JSON-in-text parsing).
+ *
+ * Two scopes are exposed:
+ *   - "user"   Entries the user owns. Save / Delete here is permission-gated
+ *              (permissionDefault: "ask" set in the registry) so the user
+ *              confirms each modification. Reading is always free.
+ *   - "dream"  The auto-consolidation workspace. Save / Delete go through
+ *              with no prompt — this is the LLM's scratch area for the
+ *              auto-dream pipeline (and also reachable in normal sessions
+ *              when the user asks to clean it up).
+ *
+ * Delete is SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
+ * by MemoryManager, so accidental deletions are recoverable by hand.
+ */
+import { MemoryManager } from "../../session/memory.js";
+const VALID_SCOPES = ["user", "dream"];
+const VALID_TYPES = ["user", "feedback", "project", "reference"];
+function parseScope(raw) {
+    if (typeof raw !== "string")
+        return "Error: scope is required (\"user\" or \"dream\")";
+    if (!VALID_SCOPES.includes(raw)) {
+        return `Error: scope must be "user" or "dream", got "${raw}"`;
+    }
+    return raw;
+}
+function mmFor(ctx, scope) {
+    return new MemoryManager({ projectDir: ctx?.cwd, scope });
+}
+// ─── MemoryList ────────────────────────────────────────────────────────────
+export const memoryListToolDef = {
+    name: "MemoryList",
+    description: "List persistent memory entries from one scope. " +
+        "Returns each entry's name, type, and short description (not the full content — use MemoryRead for that). " +
+        "Use this before MemorySave/MemoryDelete to find the exact name to target. " +
+        'Scopes: "user" (entries the user owns; you need permission to modify) or "dream" (auto-consolidation workspace; you may freely modify).',
+    inputSchema: {
+        type: "object",
+        properties: {
+            scope: {
+                type: "string",
+                enum: ["user", "dream"],
+                description: "Which scope to list",
+            },
+        },
+        required: ["scope"],
+    },
+};
+export async function memoryListTool(args, ctx) {
+    const scope = parseScope(args.scope);
+    if (typeof scope !== "string" || !VALID_SCOPES.includes(scope)) {
+        return scope;
+    }
+    try {
+        const mm = mmFor(ctx, scope);
+        const entries = mm.loadAll();
+        if (entries.length === 0)
+            return `(no memories in scope "${scope}")`;
+        return entries
+            .map((e) => `- [${e.type}] ${e.name} — ${e.description}`)
+            .join("\n");
+    }
+    catch (err) {
+        return `Error listing memories: ${err.message}`;
+    }
+}
+// ─── MemoryRead ────────────────────────────────────────────────────────────
+export const memoryReadToolDef = {
+    name: "MemoryRead",
+    description: "Read the full content of a single memory entry by name. " +
+        "Use MemoryList first to find the exact name.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            scope: {
+                type: "string",
+                enum: ["user", "dream"],
+                description: "Which scope to read from",
+            },
+            name: {
+                type: "string",
+                description: "The memory entry's name (from MemoryList output)",
+            },
+        },
+        required: ["scope", "name"],
+    },
+};
+export async function memoryReadTool(args, ctx) {
+    const scope = parseScope(args.scope);
+    if (typeof scope !== "string" || !VALID_SCOPES.includes(scope)) {
+        return scope;
+    }
+    const name = args.name;
+    if (typeof name !== "string" || !name)
+        return "Error: name is required";
+    try {
+        const mm = mmFor(ctx, scope);
+        const entries = mm.loadAll();
+        const entry = entries.find((e) => e.name === name || e.fileName === name);
+        if (!entry)
+            return `Error: no memory named "${name}" in scope "${scope}"`;
+        return (`name: ${entry.name}\n` +
+            `description: ${entry.description}\n` +
+            `type: ${entry.type}\n` +
+            `\n${entry.content}`);
+    }
+    catch (err) {
+        return `Error reading memory: ${err.message}`;
+    }
+}
+// ─── MemorySave ────────────────────────────────────────────────────────────
+export const memorySaveToolDef = {
+    name: "MemorySave",
+    description: "Create or overwrite a memory entry. Same name → overwrite. " +
+        'Saving to scope "user" requires user permission (you will see a confirmation prompt). ' +
+        'Saving to scope "dream" is automatic — it is your auto-consolidation workspace. ' +
+        "Pick `type` carefully: " +
+        "user (info about the user), " +
+        "feedback (how to approach work), " +
+        "project (non-obvious facts about ongoing work), " +
+        "reference (pointers to external resources). " +
+        "The `description` is a one-line summary shown in the index; the `content` is the full body.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            scope: {
+                type: "string",
+                enum: ["user", "dream"],
+                description: "Which scope to save to",
+            },
+            name: {
+                type: "string",
+                description: "Short kebab-case identifier (also becomes the filename slug)",
+            },
+            description: {
+                type: "string",
+                description: "One-line summary (used in the memory index)",
+            },
+            type: {
+                type: "string",
+                enum: ["user", "feedback", "project", "reference"],
+                description: "Memory category",
+            },
+            content: {
+                type: "string",
+                description: "Full memory body in markdown",
+            },
+        },
+        required: ["scope", "name", "description", "type", "content"],
+    },
+};
+export async function memorySaveTool(args, ctx) {
+    const scope = parseScope(args.scope);
+    if (typeof scope !== "string" || !VALID_SCOPES.includes(scope)) {
+        return scope;
+    }
+    const name = args.name;
+    const description = args.description;
+    const type = args.type;
+    const content = args.content;
+    if (typeof name !== "string" || !name)
+        return "Error: name is required";
+    if (typeof description !== "string")
+        return "Error: description is required";
+    if (typeof content !== "string")
+        return "Error: content is required";
+    if (typeof type !== "string" || !VALID_TYPES.includes(type)) {
+        return `Error: type must be one of ${VALID_TYPES.join(", ")}`;
+    }
+    try {
+        const mm = mmFor(ctx, scope);
+        const fileName = mm.save({
+            name,
+            description,
+            type: type,
+            content,
+        });
+        return `Saved memory "${name}" → ${scope}/${fileName}`;
+    }
+    catch (err) {
+        return `Error saving memory: ${err.message}`;
+    }
+}
+// ─── MemoryDelete ──────────────────────────────────────────────────────────
+export const memoryDeleteToolDef = {
+    name: "MemoryDelete",
+    description: "Soft-delete a memory entry by name (moves it to a trash directory; recoverable). " +
+        'Deleting from scope "user" requires user permission. ' +
+        'Deleting from scope "dream" is automatic. ' +
+        "Use MemoryList to find the exact name first.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            scope: {
+                type: "string",
+                enum: ["user", "dream"],
+                description: "Which scope to delete from",
+            },
+            name: {
+                type: "string",
+                description: "The memory entry's name (from MemoryList output)",
+            },
+        },
+        required: ["scope", "name"],
+    },
+};
+export async function memoryDeleteTool(args, ctx) {
+    const scope = parseScope(args.scope);
+    if (typeof scope !== "string" || !VALID_SCOPES.includes(scope)) {
+        return scope;
+    }
+    const name = args.name;
+    if (typeof name !== "string" || !name)
+        return "Error: name is required";
+    try {
+        const mm = mmFor(ctx, scope);
+        const ok = mm.delete(name);
+        return ok
+            ? `Deleted memory "${name}" from scope "${scope}" (moved to memory-trash/)`
+            : `Error: no memory named "${name}" in scope "${scope}"`;
+    }
+    catch (err) {
+        return `Error deleting memory: ${err.message}`;
+    }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * NotebookEditTool — read and edit Jupyter notebook (.ipynb) cells.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const notebookEditToolDef: ToolDefinition;
+export declare function notebookEditTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,124 @@
+/**
+ * NotebookEditTool — read and edit Jupyter notebook (.ipynb) cells.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+export const notebookEditToolDef = {
+    name: "NotebookEdit",
+    description: "Edit a Jupyter notebook (.ipynb) file. Supports actions: " +
+        "'read' to view cells, 'insert' to add a cell, 'replace' to update a cell, " +
+        "'delete' to remove a cell.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            file_path: {
+                type: "string",
+                description: "Path to the .ipynb file",
+            },
+            action: {
+                type: "string",
+                enum: ["read", "insert", "replace", "delete"],
+                description: "Operation to perform",
+            },
+            cell_index: {
+                type: "number",
+                description: "Cell index (0-based). Required for replace and delete.",
+            },
+            cell_type: {
+                type: "string",
+                enum: ["code", "markdown", "raw"],
+                description: "Cell type for insert/replace (default: 'code')",
+            },
+            source: {
+                type: "string",
+                description: "Cell content for insert/replace",
+            },
+        },
+        required: ["file_path", "action"],
+    },
+};
+export async function notebookEditTool(args) {
+    const filePath = args.file_path;
+    const action = args.action;
+    if (!filePath)
+        return "Error: file_path is required";
+    if (!filePath.endsWith(".ipynb"))
+        return "Error: file must be a .ipynb file";
+    if (action === "read") {
+        if (!existsSync(filePath))
+            return `Error: File not found: ${filePath}`;
+        const nb = readNotebook(filePath);
+        const lines = [`Notebook: ${filePath} (${nb.cells.length} cells)\n`];
+        nb.cells.forEach((cell, i) => {
+            const source = cell.source.join("");
+            const preview = source.slice(0, 200);
+            lines.push(`[${i}] ${cell.cell_type}: ${preview}${source.length > 200 ? "..." : ""}`);
+        });
+        return lines.join("\n");
+    }
+    if (action === "insert") {
+        const nb = existsSync(filePath) ? readNotebook(filePath) : createEmptyNotebook();
+        const cellType = args.cell_type ?? "code";
+        const source = args.source ?? "";
+        const index = args.cell_index ?? nb.cells.length;
+        const newCell = createCell(cellType, source);
+        nb.cells.splice(index, 0, newCell);
+        writeNotebook(filePath, nb);
+        return `Inserted ${cellType} cell at index ${index}.`;
+    }
+    if (action === "replace") {
+        if (!existsSync(filePath))
+            return `Error: File not found: ${filePath}`;
+        const nb = readNotebook(filePath);
+        const index = args.cell_index;
+        if (index === undefined || index < 0 || index >= nb.cells.length) {
+            return `Error: Invalid cell_index ${index}. Notebook has ${nb.cells.length} cells.`;
+        }
+        const cellType = args.cell_type ?? nb.cells[index].cell_type;
+        const source = args.source ?? "";
+        nb.cells[index] = createCell(cellType, source);
+        writeNotebook(filePath, nb);
+        return `Replaced cell ${index} with ${cellType} cell.`;
+    }
+    if (action === "delete") {
+        if (!existsSync(filePath))
+            return `Error: File not found: ${filePath}`;
+        const nb = readNotebook(filePath);
+        const index = args.cell_index;
+        if (index === undefined || index < 0 || index >= nb.cells.length) {
+            return `Error: Invalid cell_index ${index}. Notebook has ${nb.cells.length} cells.`;
+        }
+        nb.cells.splice(index, 1);
+        writeNotebook(filePath, nb);
+        return `Deleted cell ${index}. Notebook now has ${nb.cells.length} cells.`;
+    }
+    return `Unknown action: ${action}`;
+}
+function readNotebook(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+function writeNotebook(filePath, nb) {
+    writeFileSync(filePath, JSON.stringify(nb, null, 1) + "\n", "utf-8");
+}
+function createEmptyNotebook() {
+    return {
+        cells: [],
+        metadata: {
+            kernelspec: { display_name: "Python 3", language: "python", name: "python3" },
+            language_info: { name: "python", version: "3.10.0" },
+        },
+        nbformat: 4,
+        nbformat_minor: 5,
+    };
+}
+function createCell(type, source) {
+    const cell = {
+        cell_type: type,
+        source: source.split("\n").map((line, i, arr) => (i < arr.length - 1 ? line + "\n" : line)),
+        metadata: {},
+    };
+    if (type === "code") {
+        cell.outputs = [];
+        cell.execution_count = null;
+    }
+    return cell;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Plan mode — restricts the agent to read-only exploration and text output.
+ *
+ * In plan mode the agent:
+ *   - Can only use read-only tools (Read, Glob, Grep, Bash read-only, WebSearch, etc.)
+ *   - CANNOT write, edit, or create files
+ *   - Outputs its plan as text directly in the conversation
+ *   - Exits plan mode when the user approves or via ExitPlanMode tool
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const enterPlanModeToolDef: ToolDefinition;
+export declare const exitPlanModeToolDef: ToolDefinition;
+export declare function enterPlanModeTool(_args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function exitPlanModeTool(_args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;