Positron notebooks - Add new functionality to edit tool for moving cells. (#11023)

Addresses #10553.

### Summary

This PR adds notebook cell reordering capabilities to the Positron
Assistant, enabling users to reorganize cells through natural language
prompts like "move all imports to the top cell" or "move the third cell
to the bottom."



https://github.com/user-attachments/assets/0e4835d6-1466-4ad4-8541-514bcdffd2d4


The implementation extends the `EditNotebookCellsTool` with a new
`reorder` operation that supports both single cell moves (via
`fromIndex`/`toIndex`) and full permutation reordering (via `newOrder`
array). The feature includes validation for permutations and indices,
confirmation prompts for the user, and integration with the notebook
editor through the `positron.notebooks.reorderCells` API.

### Release Notes

#### New Features
- N/A

#### Bug Fixes
- N/A

### QA Notes

@:positron-notebooks @:assistant

1. Open a Jupyter notebook with multiple cells 
2. Open the Positron Assistant
3. Test single cell moves. E.g.  "Move the last cell to the top"
4. Test batch reordering. E.g. "Move all import statements to the top
cell"

Author: nstrayer

extensions/positron-assistant/package.json

@@ -845,7 +845,7 @@
       {
         "name": "editNotebookCells",
         "displayName": "Edit Notebook Cells",
-        "modelDescription": "Perform edit operations on notebook cells. Use operation='add' to create new cells (requires cellType, index, and content). Code cells are executed by default after adding (set run=false to skip execution). Use operation='update' to modify existing cells (requires cellIndex and content), or operation='delete' to remove cells (requires cellIndex). Use index=-1 to append cells at the end when adding.",
+        "modelDescription": "Perform edit operations on notebook cells. Use operation='add' to create new cells (requires cellType, index, and content). Code cells are executed by default after adding (set run=false to skip execution). Use operation='update' to modify existing cells (requires cellIndex and content), operation='delete' to remove cells (requires cellIndex), or operation='reorder' to reorganize cells. For reorder, either use fromIndex and toIndex to move a single cell, or provide newOrder array (a permutation where newOrder[i] is the original index of the cell that should be at position i) to reorder all cells at once. Use index=-1 to append cells at the end when adding.",
         "toolReferenceName": "editNotebookCells",
         "canBeReferencedInPrompt": true,
         "tags": [
@@ -860,9 +860,10 @@
               "enum": [
                 "add",
                 "update",
-                "delete"
+                "delete",
+                "reorder"
               ],
-              "description": "Type of edit operation to perform. 'add' creates a new cell, 'update' modifies existing cell content, 'delete' removes a cell."
+              "description": "Type of edit operation to perform. 'add' creates a new cell, 'update' modifies existing cell content, 'delete' removes a cell, 'reorder' moves cells to new positions."
             },
             "cellType": {
               "type": "string",
@@ -887,6 +888,21 @@
             "run": {
               "type": "boolean",
               "description": "Whether to execute the cell after adding it. Defaults to true for code cells. Ignored for markdown cells."
+            },
+            "fromIndex": {
+              "type": "number",
+              "description": "Current index of the cell to move (0-based). Required when operation is 'reorder' and not using newOrder."
+            },
+            "toIndex": {
+              "type": "number",
+              "description": "Target index to move the cell to (0-based). Required when operation is 'reorder' and not using newOrder."
+            },
+            "newOrder": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "description": "Array specifying new cell order. newOrder[i] is the original index of the cell that should be at position i. Must be a valid permutation containing each index 0 to cellCount-1 exactly once. Use this for full notebook reordering. Alternative to fromIndex/toIndex for operation='reorder'."
             }
           },
           "required": [

extensions/positron-assistant/src/tools/notebookTools.ts

@@ -7,7 +7,7 @@ import * as vscode from 'vscode';
 import * as positron from 'positron';
 import { PositronAssistantToolName } from '../types.js';
 import { log } from '../extension.js';
-import { convertOutputsToLanguageModelParts, formatCells, validateCellIndices, MAX_CELL_CONTENT_LENGTH } from './notebookUtils.js';
+import { convertOutputsToLanguageModelParts, formatCells, validateCellIndices, validatePermutation, MAX_CELL_CONTENT_LENGTH } from './notebookUtils.js';
 
 /**
  * Gets the active notebook context, returning null if no notebook is active.
@@ -144,16 +144,19 @@ export const RunNotebookCellsTool = vscode.lm.registerTool<{
 /**
  * Tool: Edit Notebook Cells
  *
- * Performs edit operations on notebook cells: add, update, or delete.
+ * Performs edit operations on notebook cells: add, update, delete, or reorder.
  * Uses a simple enum-based operation parameter for flexibility.
  */
 export const EditNotebookCellsTool = vscode.lm.registerTool<{
-	operation: 'add' | 'update' | 'delete';
+	operation: 'add' | 'update' | 'delete' | 'reorder';
 	cellType?: 'code' | 'markdown';
 	index?: number;
 	content?: string;
 	cellIndex?: number;
 	run?: boolean;
+	fromIndex?: number;
+	toIndex?: number;
+	newOrder?: number[];
 }>(PositronAssistantToolName.EditNotebookCells, {
 	prepareInvocation: async (options, _token) => {
 		const { operation, cellType, cellIndex, run } = options.input;
@@ -176,6 +179,10 @@ export const EditNotebookCellsTool = vscode.lm.registerTool<{
 					invocationMessage: vscode.l10n.t('Deleting notebook cell'),
 					pastTenseMessage: vscode.l10n.t('Deleted notebook cell'),
 				},
+				reorder: {
+					invocationMessage: vscode.l10n.t('Reordering notebook cells'),
+					pastTenseMessage: vscode.l10n.t('Reordered notebook cells'),
+				},
 			};
 			return messages[operation];
 		}
@@ -240,6 +247,35 @@ export const EditNotebookCellsTool = vscode.lm.registerTool<{
 				};
 			}
 
+			case 'reorder': {
+				const { fromIndex, toIndex, newOrder } = options.input;
+
+				// Determine if this is a single move or full reorder
+				if (newOrder !== undefined) {
+					// Full permutation reorder
+					const message = vscode.l10n.t('Reorder all {0} cells in the notebook?', context.cellCount);
+					return {
+						invocationMessage: vscode.l10n.t('Reordering notebook cells'),
+						confirmationMessages: {
+							title: vscode.l10n.t('Reorder Notebook Cells'),
+							message: message
+						},
+						pastTenseMessage: vscode.l10n.t('Reordered notebook cells'),
+					};
+				} else {
+					// Single cell move
+					const message = vscode.l10n.t('Move cell {0} to position {1}?', fromIndex, toIndex);
+					return {
+						invocationMessage: vscode.l10n.t('Moving notebook cell'),
+						confirmationMessages: {
+							title: vscode.l10n.t('Move Notebook Cell'),
+							message: message
+						},
+						pastTenseMessage: vscode.l10n.t('Moved notebook cell'),
+					};
+				}
+			}
+
 			default:
 				return {
 					invocationMessage: vscode.l10n.t('Editing notebook cell'),
@@ -248,7 +284,7 @@ export const EditNotebookCellsTool = vscode.lm.registerTool<{
 		}
 	},
 	invoke: async (options, token) => {
-		const { operation, cellType, index, content, cellIndex, run } = options.input;
+		const { operation, cellType, index, content, cellIndex, run, fromIndex, toIndex, newOrder } = options.input;
 
 		try {
 			const context = await getActiveNotebookContext();
@@ -419,10 +455,76 @@ export const EditNotebookCellsTool = vscode.lm.registerTool<{
 					]);
 				}
 
+				case 'reorder': {
+					// Determine if this is a single move or full reorder
+					if (newOrder !== undefined) {
+						// Full permutation reorder
+						const permValidation = validatePermutation(newOrder, context.cellCount);
+						if (!permValidation.valid) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart(permValidation.error!)
+							]);
+						}
+
+						// Check for identity permutation (no-op)
+						if (permValidation.isIdentity) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart('No reordering needed - cells are already in the specified order')
+							]);
+						}
+
+						await positron.notebooks.reorderCells(context.uri, newOrder);
+
+						return new vscode.LanguageModelToolResult([
+							new vscode.LanguageModelTextPart(`Successfully reordered ${context.cellCount} cells`)
+						]);
+					} else {
+						// Single cell move - validate required parameters
+						if (fromIndex === undefined) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart('Missing required parameter: fromIndex (current index of cell to move)')
+							]);
+						}
+						if (toIndex === undefined) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart('Missing required parameter: toIndex (target index to move cell to)')
+							]);
+						}
+
+						// Validate indices
+						const fromValidation = validateCellIndices([fromIndex], context.cellCount);
+						if (!fromValidation.valid) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart(`Invalid fromIndex: ${fromValidation.error}`)
+							]);
+						}
+
+						const toValidation = validateCellIndices([toIndex], context.cellCount);
+						if (!toValidation.valid) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart(`Invalid toIndex: ${toValidation.error}`)
+							]);
+						}
+
+						// Check for no-op
+						if (fromIndex === toIndex) {
+							return new vscode.LanguageModelToolResult([
+								new vscode.LanguageModelTextPart('No move needed - cell is already at the specified position')
+							]);
+						}
+
+						await positron.notebooks.moveCell(context.uri, fromIndex, toIndex);
+
+						return new vscode.LanguageModelToolResult([
+							new vscode.LanguageModelTextPart(`Successfully moved cell from index ${fromIndex} to index ${toIndex}`)
+						]);
+					}
+				}
+
 				default:
 					return new vscode.LanguageModelToolResult([
 						new vscode.LanguageModelTextPart(
-							`Unknown operation: ${operation}. Must be "add", "update", or "delete".`
+							`Unknown operation: ${operation}. Must be "add", "update", "delete", or "reorder".`
 						)
 					]);
 			}

extensions/positron-assistant/src/tools/notebookUtils.ts

@@ -70,6 +70,76 @@ export function validateCellIndices(
 	return { valid: true };
 }
 
+/**
+ * Validation result for permutation arrays
+ */
+export interface PermutationValidation {
+	valid: boolean;
+	error?: string;
+	isIdentity?: boolean;
+}
+
+/**
+ * Validates a permutation array for reordering cells.
+ * A valid permutation must contain each index from 0 to cellCount-1 exactly once.
+ *
+ * @param newOrder The proposed new order array
+ * @param cellCount The total number of cells in the notebook
+ * @returns Validation result with error message if invalid, and whether it's an identity permutation
+ */
+export function validatePermutation(
+	newOrder: number[],
+	cellCount: number
+): PermutationValidation {
+	// Check length matches
+	if (newOrder.length !== cellCount) {
+		return {
+			valid: false,
+			error: `Permutation length (${newOrder.length}) must match cell count (${cellCount})`
+		};
+	}
+
+	// Handle empty notebook case
+	if (cellCount === 0) {
+		return { valid: true, isIdentity: true };
+	}
+
+	// An identity permutation is just one where each index maps to itself. Aka a no-op.
+	let isIdentity = true;
+
+	// Check if any indices are outside of the valid range
+	for (const [i, index] of newOrder.entries()) {
+		if (!Number.isInteger(index) || index < 0 || index >= cellCount) {
+			return {
+				valid: false,
+				error: `Invalid index in permutation: ${index} (must be integer between 0 and ${cellCount - 1})`
+			};
+		}
+
+		// Check for identity at the same time
+		if (index !== i) {
+			isIdentity = false;
+		}
+	}
+
+	// If identity permutation, no need to check further
+	if (isIdentity) {
+		return { valid: true, isIdentity: true };
+	}
+
+	// Make sure there are no duplicates and all indices are present
+	const uniqueIndices = new Set(newOrder);
+
+	if (uniqueIndices.size !== cellCount) {
+		return {
+			valid: false,
+			error: 'Invalid permutation: must contain each index from 0 to cellCount-1 exactly once'
+		};
+	}
+
+	return { valid: true, isIdentity: false };
+}
+
 /**
  * Fetches and formats cell content for preview in confirmation dialogs.
  * Truncates long content with ellipsis.

src/positron-dts/positron.d.ts

@@ -2575,5 +2575,22 @@ declare module 'positron' {
 		 * @returns Array of output objects with MIME type and data
 		 */
 		export function getCellOutputs(notebookUri: string, cellIndex: number): Thenable<NotebookCellOutput[]>;
+
+		/**
+		 * Move a cell from one index to another in a notebook
+		 * @param notebookUri URI of the notebook
+		 * @param fromIndex The current index of the cell to move
+		 * @param toIndex The target index where the cell should be moved to
+		 */
+		export function moveCell(notebookUri: string, fromIndex: number, toIndex: number): Thenable<void>;
+
+		/**
+		 * Reorder all cells in a notebook according to a new order
+		 * @param notebookUri URI of the notebook
+		 * @param newOrder Array representing the new order - newOrder[i] is the index of the cell
+		 *                 that should be at position i in the reordered notebook.
+		 *                 Must be a valid permutation containing each index from 0 to cellCount-1 exactly once.
+		 */
+		export function reorderCells(notebookUri: string, newOrder: number[]): Thenable<void>;
 	}
 }