@jupyterlite/ai 0.8.0 → 0.9.0-a0

package/lib/tools/commands.js

@@ -0,0 +1,126 @@
+import { tool } from '@openai/agents';
+import { z } from 'zod';
+/**
+ * Create a tool to discover all available commands and their metadata
+ */
+export function createDiscoverCommandsTool(commands) {
+    return tool({
+        name: 'discover_commands',
+        description: 'Discover all available JupyterLab commands with their metadata, arguments, and descriptions',
+        parameters: z.object({
+            // currently unused, but could be used to filter commands by a search term
+            query: z
+                .string()
+                .optional()
+                .nullable()
+                .describe('Optional search query to filter commands')
+        }),
+        execute: async () => {
+            try {
+                const commandList = [];
+                // Get all command IDs
+                const commandIds = commands.listCommands();
+                for (const id of commandIds) {
+                    try {
+                        // Get command metadata using various CommandRegistry methods
+                        const description = await commands.describedBy(id);
+                        const label = commands.label(id);
+                        const caption = commands.caption(id);
+                        const usage = commands.usage(id);
+                        commandList.push({
+                            id,
+                            label: label || undefined,
+                            caption: caption || undefined,
+                            description: usage || undefined,
+                            args: description?.args || undefined
+                        });
+                    }
+                    catch (error) {
+                        // Some commands might not have descriptions, skip them
+                        commandList.push({ id });
+                    }
+                }
+                return {
+                    success: true,
+                    commandCount: commandList.length,
+                    commands: commandList
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to discover commands: ${error instanceof Error ? error.message : String(error)}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool to execute a specific JupyterLab command
+ */
+export function createExecuteCommandTool(commands, settingsModel) {
+    return tool({
+        name: 'execute_command',
+        description: 'Execute a specific JupyterLab command with optional arguments',
+        parameters: z.object({
+            commandId: z.string().describe('The ID of the command to execute'),
+            args: z
+                .any()
+                .optional()
+                .describe('Optional arguments to pass to the command')
+        }),
+        needsApproval: async (_context, { commandId }) => {
+            // Use configurable list of commands requiring approval
+            const commandsRequiringApproval = settingsModel.config.commandsRequiringApproval;
+            return commandsRequiringApproval.some(cmd => commandId.includes(cmd) || cmd.includes(commandId));
+        },
+        execute: async (input) => {
+            const { commandId, args } = input;
+            // Check if command exists
+            if (!commands.hasCommand(commandId)) {
+                return {
+                    success: false,
+                    error: `Command '${commandId}' does not exist. Use 'discover_commands' to see available commands.`
+                };
+            }
+            try {
+                // Execute the command
+                const result = await commands.execute(commandId, args);
+                // Handle Widget objects specially (including subclasses like DocumentWidget)
+                let serializedResult;
+                if (result &&
+                    typeof result === 'object' &&
+                    (result.constructor?.name?.includes('Widget') || result.id)) {
+                    serializedResult = {
+                        type: result.constructor?.name || 'Widget',
+                        id: result.id,
+                        title: result.title?.label || result.title,
+                        className: result.className
+                    };
+                }
+                else {
+                    // For other objects, try JSON serialization with fallback
+                    try {
+                        serializedResult = JSON.parse(JSON.stringify(result));
+                    }
+                    catch {
+                        serializedResult = result
+                            ? '[Complex object - cannot serialize]'
+                            : 'Command executed successfully';
+                    }
+                }
+                return {
+                    success: true,
+                    commandId,
+                    result: serializedResult
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to execute command '${commandId}': ${error instanceof Error ? error.message : String(error)}`
+                };
+            }
+        }
+    });
+}

package/lib/tools/file.d.ts

@@ -0,0 +1,27 @@
+import { CommandRegistry } from '@lumino/commands';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITool } from '../tokens';
+/**
+ * Create a tool for creating new files of various types
+ */
+export declare function createNewFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for opening files
+ */
+export declare function createOpenFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for deleting files
+ */
+export declare function createDeleteFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for renaming files
+ */
+export declare function createRenameFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for copying files
+ */
+export declare function createCopyFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for navigating to directories in the file browser
+ */
+export declare function createNavigateToDirectoryTool(commands: CommandRegistry): ITool;

package/lib/tools/file.js

@@ -0,0 +1,262 @@
+import { tool } from '@openai/agents';
+import { z } from 'zod';
+/**
+ * Create a tool for creating new files of various types
+ */
+export function createNewFileTool(docManager) {
+    return tool({
+        name: 'create_file',
+        description: 'Create a new file of specified type (text, python, markdown, json, etc.)',
+        parameters: z.object({
+            fileName: z.string().describe('Name of the file to create'),
+            fileType: z
+                .enum([
+                'text',
+                'python',
+                'markdown',
+                'json',
+                'javascript',
+                'typescript'
+            ])
+                .default('text')
+                .describe('Type of file to create'),
+            content: z
+                .string()
+                .optional()
+                .nullable()
+                .describe('Initial content for the file (optional)'),
+            cwd: z
+                .string()
+                .optional()
+                .nullable()
+                .describe('Directory where to create the file (optional)')
+        }),
+        execute: async (input) => {
+            const { fileName, content = '', cwd, fileType = 'text' } = input;
+            try {
+                // Determine file extension based on type
+                const extensions = {
+                    python: 'py',
+                    markdown: 'md',
+                    json: 'json',
+                    text: 'txt',
+                    javascript: 'js',
+                    typescript: 'ts'
+                };
+                const ext = extensions[fileType] || 'txt';
+                // If fileName already has an extension, use it as-is, otherwise add the extension
+                const fullFileName = fileName.includes('.')
+                    ? fileName
+                    : `${fileName}.${ext}`;
+                // For Python files, ensure .py extension if fileType is python
+                const finalFileName = fileType === 'python' &&
+                    !fileName.endsWith('.py') &&
+                    !fileName.includes('.')
+                    ? `${fileName}.py`
+                    : fullFileName;
+                const fullPath = cwd ? `${cwd}/${finalFileName}` : finalFileName;
+                // Create file with content using document manager
+                const model = await docManager.services.contents.newUntitled({
+                    path: cwd || '',
+                    type: 'file',
+                    ext
+                });
+                // Rename to desired name if needed
+                let finalPath = model.path;
+                if (model.name !== finalFileName) {
+                    const renamed = await docManager.services.contents.rename(model.path, fullPath);
+                    finalPath = renamed.path;
+                }
+                // Set content if provided
+                if (content) {
+                    await docManager.services.contents.save(finalPath, {
+                        type: 'file',
+                        format: 'text',
+                        content
+                    });
+                }
+                // Open the newly created file
+                let opened = false;
+                if (!docManager.findWidget(finalPath)) {
+                    docManager.openOrReveal(finalPath);
+                    opened = true;
+                }
+                return {
+                    success: true,
+                    message: `${fileType} file '${finalFileName}' created and opened successfully`,
+                    fileName: finalFileName,
+                    filePath: finalPath,
+                    fileType,
+                    hasContent: !!content,
+                    opened
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to create file: ${error.message}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool for opening files
+ */
+export function createOpenFileTool(docManager) {
+    return tool({
+        name: 'open_file',
+        description: 'Open a file in the editor',
+        parameters: z.object({
+            filePath: z.string().describe('Path to the file to open')
+        }),
+        execute: async (input) => {
+            const { filePath } = input;
+            try {
+                const widget = docManager.openOrReveal(filePath);
+                if (!widget) {
+                    return {
+                        success: false,
+                        error: `Failed to open file: ${filePath}`
+                    };
+                }
+                return {
+                    success: true,
+                    message: `File '${filePath}' opened successfully`,
+                    filePath,
+                    widgetId: widget.id
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to open file: ${error.message}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool for deleting files
+ */
+export function createDeleteFileTool(docManager) {
+    return tool({
+        name: 'delete_file',
+        description: 'Delete a file from the file system',
+        parameters: z.object({
+            filePath: z.string().describe('Path to the file to delete')
+        }),
+        execute: async (input) => {
+            const { filePath } = input;
+            try {
+                await docManager.services.contents.delete(filePath);
+                return {
+                    success: true,
+                    message: `File '${filePath}' deleted successfully`,
+                    filePath
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to delete file: ${error.message}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool for renaming files
+ */
+export function createRenameFileTool(docManager) {
+    return tool({
+        name: 'rename_file',
+        description: 'Rename a file or move it to a different location',
+        parameters: z.object({
+            oldPath: z.string().describe('Current path of the file'),
+            newPath: z.string().describe('New path/name for the file')
+        }),
+        execute: async (input) => {
+            const { oldPath, newPath } = input;
+            try {
+                await docManager.services.contents.rename(oldPath, newPath);
+                return {
+                    success: true,
+                    message: `File renamed from '${oldPath}' to '${newPath}' successfully`,
+                    oldPath,
+                    newPath
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to rename file: ${error.message}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool for copying files
+ */
+export function createCopyFileTool(docManager) {
+    return tool({
+        name: 'copy_file',
+        description: 'Copy a file to a new location',
+        parameters: z.object({
+            sourcePath: z.string().describe('Path of the file to copy'),
+            destinationPath: z
+                .string()
+                .describe('Destination path for the copied file')
+        }),
+        execute: async (input) => {
+            const { sourcePath, destinationPath } = input;
+            try {
+                await docManager.services.contents.copy(sourcePath, destinationPath);
+                return {
+                    success: true,
+                    message: `File copied from '${sourcePath}' to '${destinationPath}' successfully`,
+                    sourcePath,
+                    destinationPath
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to copy file: ${error.message}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool for navigating to directories in the file browser
+ */
+export function createNavigateToDirectoryTool(commands) {
+    return tool({
+        name: 'navigate_to_directory',
+        description: 'Navigate to a specific directory in the file browser',
+        parameters: z.object({
+            directoryPath: z.string().describe('Path to the directory to navigate to')
+        }),
+        execute: async (input) => {
+            const { directoryPath } = input;
+            try {
+                await commands.execute('filebrowser:go-to-path', {
+                    path: directoryPath
+                });
+                return {
+                    success: true,
+                    message: `Navigated to directory '${directoryPath}' successfully`,
+                    directoryPath
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to navigate to directory: ${error.message}`
+                };
+            }
+        }
+    });
+}

package/lib/tools/notebook.d.ts

@@ -0,0 +1,40 @@
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { INotebookTracker } from '@jupyterlab/notebook';
+import { KernelSpec } from '@jupyterlab/services';
+import { ITool } from '../tokens';
+/**
+ * Create a notebook creation tool
+ */
+export declare function createNotebookCreationTool(docManager: IDocumentManager, kernelSpecManager: KernelSpec.IManager): ITool;
+/**
+ * Create a tool for adding cells to a specific notebook
+ */
+export declare function createAddCellTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for getting notebook information
+ */
+export declare function createGetNotebookInfoTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for getting cell information by index
+ */
+export declare function createGetCellInfoTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for setting cell content and type
+ */
+export declare function createSetCellContentTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for running a specific cell
+ */
+export declare function createRunCellTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for deleting a specific cell
+ */
+export declare function createDeleteCellTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for executing code in the active cell (non-disruptive alternative to mcp__ide__executeCode)
+ */
+export declare function createExecuteActiveCellTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;
+/**
+ * Create a tool for saving a specific notebook
+ */
+export declare function createSaveNotebookTool(docManager: IDocumentManager, notebookTracker?: INotebookTracker): ITool;