one-code-extension 0.1.3 → 0.3.0

package/extensions/notebook/index.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
-import { applyEdit, type EditMode, parseNotebook } from "./notebook.ts";
+import { applyEdit, type EditMode, type Notebook, notebookErrorHint, parseNotebook } from "./notebook.ts";
 
 export default function notebookExtension(pi: ExtensionAPI) {
 	pi.registerTool({
@@ -20,52 +20,70 @@ export default function notebookExtension(pi: ExtensionAPI) {
 		label: "Notebook Edit",
 		...ccToolRenderers("Notebook Edit"),
 		description:
-			"Edit a Jupyter notebook (.ipynb): replace a cell's source, insert a new cell, or delete a cell. Cells are addressed by their `id`; read the notebook first to get ids. Editing a code cell clears its outputs.",
+			"Edit a Jupyter notebook (.ipynb): replace a cell's source, insert or append a new cell, or delete a cell. Read the notebook first — like the other file tools, this one refuses to edit a file you have not read. Cells are addressed by their `id` or, for a notebook whose cells have none, by position — `cell-0` is the first cell. Use edit_mode `append` to add a cell at the end without naming one. Editing a code cell clears its outputs.",
 		parameters: Type.Object({
-			path: Type.String({ description: "Absolute or workspace-relative path to the .ipynb file" }),
-			edit_mode: StringEnum(["replace", "insert", "delete"] as const),
+			path: Type.Optional(Type.String({ description: "Absolute or workspace-relative path to the .ipynb file" })),
+			// Claude Code's NotebookEdit spells the path `notebook_path` and defaults
+			// edit_mode to `replace`; a CC-trained model's `{notebook_path, cell_id,
+			// new_source}` used to fail schema validation twice over
+			// (TOOL-FIDELITY-REVIEW-2026-09-07 M2). Accept both.
+			notebook_path: Type.Optional(Type.String({ description: "Alias of `path` (Claude Code's name for it)." })),
+			edit_mode: Type.Optional(StringEnum(["replace", "insert", "append", "delete"] as const, { description: "The type of edit to make. Defaults to replace." })),
 			cell_id: Type.Optional(
 				Type.String({
 					description:
-						"Target cell id. Required for replace and delete; for insert the new cell goes after it (omit to insert at the top).",
+						"Target cell id, either the cell's own id or its position as `cell-0`, `cell-1`, … Required for replace and delete; for insert the new cell goes after it (omit to insert at the top); ignored for append.",
 				}),
 			),
 			new_source: Type.Optional(Type.String({ description: "New cell source. Required unless deleting." })),
 			cell_type: Type.Optional(
 				StringEnum(["code", "markdown"] as const, {
-					description: "Cell type. Required when inserting; when replacing, changes the cell's type.",
+					description: "Cell type. Required when inserting or appending; when replacing, changes the cell's type.",
 				}),
 			),
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const path = isAbsolute(params.path) ? params.path : resolve(ctx.cwd, params.path);
+			const rawPath = params.path ?? params.notebook_path;
+			if (!rawPath) {
+				return {
+					content: [{ type: "text", text: "`path` (or Claude Code's `notebook_path`) is required: the .ipynb file to edit." }],
+					details: {},
+					isError: true,
+				};
+			}
+			const editMode = (params.edit_mode ?? "replace") as EditMode;
+			const path = isAbsolute(rawPath) ? rawPath : resolve(ctx.cwd, rawPath);
+			// Held outside the try so a failure raised AFTER the parse can name the
+			// ids the notebook actually has — a bare "cell_id is required" left both
+			// weak tiers patching ids in by hand with bash (review M4).
+			let parsed: Notebook | undefined;
 			try {
-				const notebook = parseNotebook(readFileSync(path, "utf-8"));
+				const notebook = (parsed = parseNotebook(readFileSync(path, "utf-8")));
 				const { notebook: updated, summary } = applyEdit(
 					notebook,
 					{
 						cellId: params.cell_id,
 						newSource: params.new_source,
 						cellType: params.cell_type as "code" | "markdown" | undefined,
-						editMode: params.edit_mode as EditMode,
+						editMode,
 					},
 					() => randomUUID().slice(0, 8),
 				);
 				writeFileSync(path, `${JSON.stringify(updated, null, 1)}\n`);
 				return {
-					content: [{ type: "text", text: `${summary} in ${params.path} (${updated.cells.length} cells).` }],
+					content: [{ type: "text", text: `${summary} in ${rawPath} (${updated.cells.length} cells).` }],
 					details: { path, cellCount: updated.cells.length },
 				};
 			} catch (error) {
-				const code = (error as NodeJS.ErrnoException).code;
-				const hint =
-					code === "ENOENT"
-						? " — no such file; check the path points to an existing .ipynb"
-						: error instanceof SyntaxError
-							? " — the file is not valid notebook JSON"
-							: "";
+				const message = (error as Error).message;
+				const hint = notebookErrorHint({
+					code: (error as NodeJS.ErrnoException).code,
+					syntax: error instanceof SyntaxError,
+					message,
+					parsed,
+				});
 				return {
-					content: [{ type: "text", text: `Notebook edit failed: ${(error as Error).message}${hint}` }],
+					content: [{ type: "text", text: `Notebook edit failed: ${message}${hint}` }],
 					details: {},
 					isError: true,
 				};

package/extensions/notebook/notebook.ts

@@ -1,5 +1,15 @@
 /**
  * Jupyter notebook editing (pure) — Claude Code's NotebookEdit semantics.
+ *
+ * Cells are addressed by `id`, but nbformat only made `id` mandatory in 4.5:
+ * a 4.4-era notebook has none, and a model handed one had no id to pass and no
+ * way to append. Both a cheap-tier and a tiny-tier model fell back to bash plus
+ * `nbformat`/`json` to patch ids in — the exact route the prompt had told them
+ * not to take — 6/6 runs (WEAK-MODEL-REVIEW-2026-09-06 M4). So cells are also
+ * addressable by POSITION, as Claude Code's Read renders them: `cell-0`,
+ * `cell-1`, … Positional ids are resolved against the notebook as it is when
+ * the call arrives, so they shift after an insert or a delete — which is why
+ * every failure enumerates the notebook's current cells.
  */
 
 export interface NotebookCell {
@@ -16,7 +26,7 @@ export interface Notebook {
 	[key: string]: unknown;
 }
 
-export type EditMode = "replace" | "insert" | "delete";
+export type EditMode = "replace" | "insert" | "append" | "delete";
 
 export interface EditRequest {
 	cellId?: string;
@@ -37,12 +47,69 @@ export function toSourceLines(source: string): string[] {
 	return lines.map((line, i) => (i === lines.length - 1 ? line : `${line}\n`)).filter((l, i) => l !== "" || i === 0);
 }
 
+/** The positional id of a cell, Claude Code's spelling. */
+export function positionalId(index: number): string {
+	return `cell-${index}`;
+}
+
+/** How a cell should be named back to the model: its own id, else its position. */
+export function cellLabel(cell: NotebookCell, index: number): string {
+	return cell.id ?? positionalId(index);
+}
+
+/** `aaa (markdown), cell-1 (code)` — every id the notebook currently answers to. */
+export function describeCells(notebook: Notebook): string {
+	if (notebook.cells.length === 0) return "(none — the notebook has no cells)";
+	return notebook.cells.map((cell, index) => `${cellLabel(cell, index)} (${cell.cell_type})`).join(", ");
+}
+
+/**
+ * Trailing hint appended to a notebook_edit failure message. A missing file or
+ * malformed JSON gets a targeted pointer; a cell-addressing failure (a missing or
+ * wrong `cell_id`) gets the list of ids the notebook actually has, so a weak tier
+ * picks a real one instead of inventing it by hand (review M4). A missing
+ * `new_source`/`cell_type` is not about a cell, so it gets no id listing — that
+ * would misdirect (code-review F3). A real "No cell with id" already lists them,
+ * so it is left untouched.
+ */
+export function notebookErrorHint(opts: { code?: string; syntax: boolean; message: string; parsed: Notebook | undefined }): string {
+	if (opts.code === "ENOENT") return " — no such file; check the path points to an existing .ipynb";
+	if (opts.syntax) return " — the file is not valid notebook JSON";
+	if (opts.parsed && opts.message.includes("cell_id") && !opts.message.includes("cells are:")) {
+		return ` — this notebook's cells are: ${describeCells(opts.parsed)}. Address a cell by its own id or by position (cell-0 is the first); edit_mode "append" adds one at the end.`;
+	}
+	return "";
+}
+
+/** Index of a cell by its own id, or by its `cell-N` position. -1 when neither matches. */
 export function findCellIndex(notebook: Notebook, cellId: string): number {
-	return notebook.cells.findIndex((cell) => cell.id === cellId);
+	const byId = notebook.cells.findIndex((cell) => cell.id === cellId);
+	if (byId !== -1) return byId;
+	const positional = /^cell-(\d+)$/.exec(cellId);
+	if (!positional) return -1;
+	const index = Number.parseInt(positional[1], 10);
+	return index < notebook.cells.length ? index : -1;
 }
 
-function newCell(cellType: "code" | "markdown", source: string, id: string): NotebookCell {
-	const cell: NotebookCell = { cell_type: cellType, id, metadata: {}, source: toSourceLines(source) };
+/**
+ * The "fail loud, name the fix" error for an id that resolves to nothing
+ * (docs/decisions/tools.md): which ids exist, and the two ways to add a cell
+ * without naming one.
+ */
+export function noSuchCellError(notebook: Notebook, cellId: string): Error {
+	return new Error(
+		`No cell with id "${cellId}". This notebook's cells are: ${describeCells(notebook)}. ` +
+			"Cells can be addressed by their own id or by position (cell-0 is the first). " +
+			'To add a cell without naming one, use edit_mode "append" (at the end) or omit cell_id with edit_mode "insert" (at the top).',
+	);
+}
+
+function newCell(cellType: "code" | "markdown", source: string, id: string | undefined): NotebookCell {
+	const cell: NotebookCell = { cell_type: cellType, metadata: {}, source: toSourceLines(source) };
+	// A 4.4 notebook has no legal `id` field, so a new cell must not carry one
+	// either — stamping one would leave a single id-bearing cell among id-less
+	// ones, which is exactly the shape withRepairedIds refuses to create.
+	if (id !== undefined) cell.id = id;
 	if (cellType === "code") {
 		cell.outputs = [];
 		cell.execution_count = null;
@@ -50,6 +117,23 @@ function newCell(cellType: "code" | "markdown", source: string, id: string): Not
 	return cell;
 }
 
+/**
+ * nbformat 4.5 REQUIRES every cell to carry an id, so a 4.5+ notebook missing
+ * them is malformed and filling them in on the way out is a repair, not a
+ * rewrite. A 4.4 notebook is left alone: `id` is not a legal cell field there,
+ * and its cells stay addressable by position.
+ */
+function supportsIds(notebook: Notebook): boolean {
+	const minor = typeof notebook.nbformat_minor === "number" ? notebook.nbformat_minor : 0;
+	const major = typeof notebook.nbformat === "number" ? notebook.nbformat : 4;
+	return major > 4 || (major === 4 && minor >= 5);
+}
+
+function withRepairedIds(notebook: Notebook, cells: NotebookCell[], makeId: () => string): NotebookCell[] {
+	if (!supportsIds(notebook)) return cells;
+	return cells.map((cell) => (cell.id ? cell : { ...cell, id: makeId() }));
+}
+
 export interface EditResult {
 	notebook: Notebook;
 	summary: string;
@@ -61,35 +145,44 @@ export interface EditResult {
  */
 export function applyEdit(notebook: Notebook, request: EditRequest, makeId: () => string): EditResult {
 	const cells = [...notebook.cells];
+	const finish = (updated: NotebookCell[], summary: string): EditResult => ({
+		notebook: { ...notebook, cells: withRepairedIds(notebook, updated, makeId) },
+		summary,
+	});
 
 	if (request.editMode === "delete") {
 		if (!request.cellId) throw new Error("cell_id is required for edit_mode 'delete'");
 		const index = findCellIndex(notebook, request.cellId);
-		if (index === -1) throw new Error(`No cell with id "${request.cellId}"`);
+		if (index === -1) throw noSuchCellError(notebook, request.cellId);
+		const label = cellLabel(cells[index], index);
 		cells.splice(index, 1);
-		return { notebook: { ...notebook, cells }, summary: `Deleted cell ${request.cellId}` };
+		return finish(cells, `Deleted cell ${label}`);
 	}
 
 	if (request.newSource === undefined) throw new Error("new_source is required unless edit_mode is 'delete'");
 
-	if (request.editMode === "insert") {
-		if (!request.cellType) throw new Error("cell_type is required for edit_mode 'insert'");
-		const id = makeId();
-		const cell = newCell(request.cellType, request.newSource, id);
+	if (request.editMode === "insert" || request.editMode === "append") {
+		if (!request.cellType) throw new Error(`cell_type is required for edit_mode '${request.editMode}'`);
+		const cell = newCell(request.cellType, request.newSource, supportsIds(notebook) ? makeId() : undefined);
+		if (request.editMode === "append") {
+			cells.push(cell);
+			// Named the way the model must address it next: its id, or its position
+			// in a notebook that has none.
+			return finish(cells, `Appended ${request.cellType} cell ${cellLabel(cell, cells.length - 1)} at the end`);
+		}
 		// Claude Code inserts AFTER the given cell; no cell_id means insert first.
 		const index = request.cellId ? findCellIndex(notebook, request.cellId) : -1;
-		if (request.cellId && index === -1) throw new Error(`No cell with id "${request.cellId}"`);
+		if (request.cellId && index === -1) throw noSuchCellError(notebook, request.cellId);
+		const afterLabel = request.cellId ? cellLabel(notebook.cells[index], index) : undefined;
 		cells.splice(index + 1, 0, cell);
-		return {
-			notebook: { ...notebook, cells },
-			summary: `Inserted ${request.cellType} cell ${id}${request.cellId ? ` after ${request.cellId}` : " at the top"}`,
-		};
+		return finish(cells, `Inserted ${request.cellType} cell ${cellLabel(cell, index + 1)}${afterLabel ? ` after ${afterLabel}` : " at the top"}`);
 	}
 
 	if (!request.cellId) throw new Error("cell_id is required for edit_mode 'replace'");
 	const index = findCellIndex(notebook, request.cellId);
-	if (index === -1) throw new Error(`No cell with id "${request.cellId}"`);
+	if (index === -1) throw noSuchCellError(notebook, request.cellId);
 	const existing = cells[index];
+	const label = cellLabel(existing, index);
 	const cellType = (request.cellType ?? existing.cell_type) as "code" | "markdown";
 	const replacement: NotebookCell = {
 		...existing,
@@ -104,5 +197,5 @@ export function applyEdit(notebook: Notebook, request: EditRequest, makeId: () =
 		delete replacement.execution_count;
 	}
 	cells[index] = replacement;
-	return { notebook: { ...notebook, cells }, summary: `Replaced cell ${request.cellId}` };
+	return finish(cells, `Replaced cell ${label}`);
 }