@dungle-scrubs/tallow 0.8.7 → 0.8.8

package/extensions/plan-mode-tool/index.ts

@@ -101,6 +101,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 	let planModeEnabled = false;
 	let executionMode = false;
 	let todoItems: TodoItem[] = [];
+	let currentStepIndex: number | null = null;
 	let normalModeTools: string[] = [];
 
 	/**
@@ -149,6 +150,45 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		return normalModeTools;
 	}
 
+	/**
+	 * Computes the current step index from todo completion state.
+	 *
+	 * @param items - Ordered todo items
+	 * @returns Zero-based index of first incomplete step, or null when complete
+	 */
+	function computeCurrentStepIndex(items: readonly TodoItem[]): number | null {
+		const nextIndex = items.findIndex((item) => !item.completed);
+		return nextIndex >= 0 ? nextIndex : null;
+	}
+
+	/**
+	 * Synchronizes currentStepIndex with todo completion state.
+	 *
+	 * @returns Updated current step index
+	 */
+	function syncCurrentStepIndex(): number | null {
+		currentStepIndex = computeCurrentStepIndex(todoItems);
+		return currentStepIndex;
+	}
+
+	/**
+	 * Gets the current step item for execution guidance.
+	 *
+	 * @returns Current step todo item, or null if all steps are complete
+	 */
+	function getCurrentStep(): TodoItem | null {
+		if (todoItems.length === 0) return null;
+		if (
+			currentStepIndex === null ||
+			currentStepIndex < 0 ||
+			currentStepIndex >= todoItems.length ||
+			todoItems[currentStepIndex]?.completed
+		) {
+			syncCurrentStepIndex();
+		}
+		return currentStepIndex === null ? null : (todoItems[currentStepIndex] ?? null);
+	}
+
 	pi.registerFlag("plan", {
 		description: "Start in plan mode (read-only exploration)",
 		type: "boolean",
@@ -227,6 +267,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		planModeEnabled = !planModeEnabled;
 		executionMode = false;
 		todoItems = [];
+		currentStepIndex = null;
 
 		if (planModeEnabled) {
 			captureNormalModeTools();
@@ -249,6 +290,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 			executing: executionMode,
 			normalTools: normalModeTools,
 			todos: todoItems,
+			currentStepIndex,
 		});
 	}
 
@@ -347,6 +389,7 @@ Use action "enable" to enter plan mode, "disable" to exit, or "status" to check
 			planModeEnabled = shouldEnable;
 			executionMode = false;
 			todoItems = [];
+			currentStepIndex = null;
 
 			let activeTools: string[];
 			if (planModeEnabled) {
@@ -455,18 +498,27 @@ Do NOT attempt to make changes - just describe what you would do.`,
 		}
 
 		if (executionMode && todoItems.length > 0) {
+			syncCurrentStepIndex();
+			const currentStep = getCurrentStep();
 			const remaining = todoItems.filter((t) => !t.completed);
 			const todoList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
+			const currentStepText = currentStep
+				? `${currentStep.step}. ${currentStep.text}`
+				: "(all steps completed)";
 			return {
 				message: {
 					customType: "plan-execution-context",
 					content: `[EXECUTING PLAN - Full tool access enabled]
 
+Current step:
+${currentStepText}
+
 Remaining steps:
 ${todoList}
 
 Execute each step in order.
-After completing a step, include a [DONE:n] tag in your response.`,
+After completing a step, include a [DONE:n] tag in your response.
+If you receive [PLAN GUIDANCE — Step n: ...], treat it as user steering for that step and apply it before continuing.`,
 					display: false,
 				},
 			};
@@ -479,12 +531,59 @@ After completing a step, include a [DONE:n] tag in your response.`,
 		if (!isAssistantMessage(event.message)) return;
 
 		const text = getTextContent(event.message);
-		if (markCompletedSteps(text, todoItems) > 0) {
+		const completedCount = markCompletedSteps(text, todoItems);
+		if (completedCount > 0) {
+			syncCurrentStepIndex();
 			updateStatus(ctx);
 		}
 		persistState();
 	});
 
+	// Offer user steering when a tool is blocked during tracked execution.
+	pi.on("tool_result", async (event, ctx) => {
+		if (!executionMode || !event.isError || !ctx.hasUI || todoItems.length === 0) return;
+
+		const currentStep = getCurrentStep();
+		if (!currentStep) return;
+
+		const errorText = Array.isArray(event.content)
+			? event.content
+					.filter((block): block is TextContent => block.type === "text")
+					.map((block) => block.text)
+					.join("\n")
+					.trim()
+			: "";
+
+		const shouldProvideGuidance = await ctx.ui.confirm(
+			"Plan step blocked",
+			[
+				`Tool "${event.toolName}" was blocked while executing step ${currentStep.step}.`,
+				"",
+				currentStep.text,
+				"",
+				`Error: ${errorText || "No error details provided."}`,
+				"",
+				"Provide guidance before execution continues?",
+			].join("\n")
+		);
+		if (!shouldProvideGuidance) return;
+
+		const guidance = await ctx.ui.editor(`Guidance for step ${currentStep.step}:`, "");
+		const trimmedGuidance = guidance?.trim();
+		if (!trimmedGuidance) return;
+
+		pi.sendUserMessage(
+			[
+				`[PLAN GUIDANCE — Step ${currentStep.step}: ${currentStep.text}]`,
+				`Tool "${event.toolName}" was blocked.`,
+				"",
+				"User guidance:",
+				trimmedGuidance,
+			].join("\n"),
+			{ deliverAs: "steer" }
+		);
+	});
+
 	// Handle plan completion and plan mode UI
 	pi.on("agent_end", async (event, ctx) => {
 		// Check if execution is complete
@@ -501,6 +600,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 				);
 				executionMode = false;
 				todoItems = [];
+				currentStepIndex = null;
 				restoreNormalModeTools();
 				updateStatus(ctx);
 				persistState(); // Save cleared state so resume doesn't restore old execution mode
@@ -543,12 +643,19 @@ After completing a step, include a [DONE:n] tag in your response.`,
 		if (choice?.startsWith("Execute")) {
 			planModeEnabled = false;
 			executionMode = todoItems.length > 0;
+			if (executionMode) {
+				syncCurrentStepIndex();
+			} else {
+				currentStepIndex = null;
+			}
 			restoreNormalModeTools();
 			updateStatus(ctx);
+			persistState();
 
+			const currentStep = getCurrentStep();
 			const execMessage =
-				todoItems.length > 0
-					? `Execute the plan. Start with: ${todoItems[0].text}`
+				currentStep !== null
+					? `Execute the plan. Start with step ${currentStep.step}: ${currentStep.text}`
 					: "Execute the plan you just created.";
 			pi.sendMessage(
 				{ customType: "plan-mode-execute", content: execMessage, display: true },
@@ -587,6 +694,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 						executing?: boolean;
 						normalTools?: string[];
 						todos?: TodoItem[];
+						currentStepIndex?: number | null;
 					};
 			  }
 			| undefined;
@@ -596,6 +704,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 			executionMode = planModeEntry.data.executing ?? executionMode;
 			normalModeTools = planModeEntry.data.normalTools ?? normalModeTools;
 			todoItems = planModeEntry.data.todos ?? todoItems;
+			currentStepIndex = planModeEntry.data.currentStepIndex ?? currentStepIndex;
 		}
 
 		// On resume: re-scan messages to rebuild completion state
@@ -628,6 +737,12 @@ After completing a step, include a [DONE:n] tag in your response.`,
 			markCompletedSteps(allText, todoItems);
 		}
 
+		if (executionMode && todoItems.length > 0) {
+			syncCurrentStepIndex();
+		} else {
+			currentStepIndex = null;
+		}
+
 		if (normalModeTools.length === 0) {
 			captureNormalModeTools();
 		}

package/extensions/prompt-suggestions/index.ts

@@ -12,8 +12,6 @@
  */
 
 import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import type { Api, Model } from "@mariozechner/pi-ai";
 import { completeSimple } from "@mariozechner/pi-ai";
 import {
@@ -22,6 +20,7 @@ import {
 	type ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
 import type { EditorTheme } from "@mariozechner/pi-tui";
+import { getTallowSettingsPath } from "../_shared/tallow-paths.js";
 import { AutocompleteEngine, type ConversationContext } from "./autocomplete.js";
 import { GENERAL_TEMPLATES, type PromptTemplate } from "./templates.js";
 
@@ -30,7 +29,7 @@ import { GENERAL_TEMPLATES, type PromptTemplate } from "./templates.js";
 /** Read a setting from ~/.tallow/settings.json with a typed fallback. */
 function readSetting<T>(key: string, fallback: T): T {
 	try {
-		const raw = readFileSync(join(homedir(), ".tallow", "settings.json"), "utf-8");
+		const raw = readFileSync(getTallowSettingsPath(), "utf-8");
 		const settings = JSON.parse(raw);
 		return key in settings ? (settings[key] as T) : fallback;
 	} catch {

package/extensions/random-spinner/index.ts

@@ -12,10 +12,9 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Loader } from "@mariozechner/pi-tui";
+import { getTallowSettingsPath } from "../_shared/tallow-paths.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -599,7 +598,7 @@ function resolve(name: string): SpinnerPreset | undefined {
  * @returns Parsed spinner settings with defaults
  */
 function readSettings(): SpinnerSettings {
-	const settingsPath = path.join(os.homedir(), ".tallow", "settings.json");
+	const settingsPath = getTallowSettingsPath();
 	try {
 		const raw = fs.readFileSync(settingsPath, "utf-8");
 		return JSON.parse(raw) as SpinnerSettings;

package/extensions/read-tool-enhanced/__tests__/notebook-read.test.ts

@@ -0,0 +1,100 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { ExtensionHarness } from "../../../test-utils/extension-harness.js";
+import readSummary from "../index.js";
+
+/**
+ * Build a small notebook fixture for end-to-end read-tool execution.
+ *
+ * @returns Serialized notebook JSON string
+ */
+function createNotebookFixture(): string {
+	return JSON.stringify({
+		metadata: {
+			kernelspec: {
+				language: "python",
+			},
+		},
+		cells: [
+			{
+				cell_type: "markdown",
+				source: ["# Header\n", "Notebook body\n"],
+			},
+			{
+				cell_type: "code",
+				execution_count: 1,
+				source: ["print('ok')\n"],
+				outputs: [
+					{
+						output_type: "stream",
+						name: "stdout",
+						text: ["ok\n"],
+					},
+				],
+			},
+		],
+	});
+}
+
+/**
+ * Build a minimal extension context stub for tool execution.
+ *
+ * @param cwd - Working directory for tool execution
+ * @returns Partial context cast to ExtensionContext
+ */
+function stubContext(cwd: string): ExtensionContext {
+	return {
+		hasUI: false,
+		ui: { setWorkingMessage() {} },
+		cwd,
+	} as unknown as ExtensionContext;
+}
+
+let notebookPath: string;
+let tmpDir: string;
+
+beforeAll(() => {
+	tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "notebook-read-test-"));
+	notebookPath = path.join(tmpDir, "sample.ipynb");
+	fs.writeFileSync(notebookPath, createNotebookFixture(), "utf-8");
+});
+
+afterAll(() => {
+	fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("read tool notebook integration", () => {
+	test("reads notebook with summarized result and full text details", async () => {
+		const harness = ExtensionHarness.create();
+		await harness.loadExtension(readSummary);
+
+		const tool = harness.tools.get("read");
+		expect(tool).toBeDefined();
+		if (!tool) return;
+
+		const updates: Array<{ details?: Record<string, unknown> }> = [];
+		const result = await tool.execute(
+			"test-id",
+			{ path: notebookPath },
+			new AbortController().signal,
+			(partial) => {
+				updates.push(partial as { details?: Record<string, unknown> });
+			},
+			stubContext(tmpDir)
+		);
+
+		const summary = result.content[0]?.type === "text" ? result.content[0].text : "";
+		const details = result.details as Record<string, unknown>;
+
+		expect(summary).toContain("sample.ipynb (2 cells");
+		expect(details.__notebook_read__).toBe(true);
+		expect(details._cellCount).toBe(2);
+		expect(typeof details._fullText).toBe("string");
+		expect(String(details._fullText)).toContain("Cell 1 [markdown]");
+		expect(String(details._fullText)).toContain("```python");
+		expect(updates.some((update) => Boolean(update.details?._preview))).toBe(true);
+	});
+});

package/extensions/read-tool-enhanced/__tests__/notebook.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import {
+	formatNotebookOutput,
+	isNotebook,
+	NotebookParseError,
+	parseNotebook,
+	summarizeNotebookCounts,
+} from "../notebook.js";
+
+/**
+ * Build a representative notebook fixture with markdown, code, and rich outputs.
+ *
+ * @returns Serialized notebook JSON string
+ */
+function createSampleNotebook(): string {
+	return JSON.stringify({
+		metadata: {
+			kernelspec: {
+				language: "python",
+			},
+		},
+		cells: [
+			{
+				cell_type: "markdown",
+				source: ["# Notebook title\n", "Some markdown context\n"],
+			},
+			{
+				cell_type: "code",
+				execution_count: 5,
+				source: ["print('hello')\n"],
+				outputs: [
+					{
+						output_type: "stream",
+						name: "stdout",
+						text: ["hello\n"],
+					},
+				],
+			},
+			{
+				cell_type: "code",
+				execution_count: 6,
+				source: ["1 / 0\n"],
+				outputs: [
+					{
+						output_type: "error",
+						ename: "ZeroDivisionError",
+						evalue: "division by zero",
+						traceback: [
+							"Traceback (most recent call last):",
+							"ZeroDivisionError: division by zero",
+						],
+					},
+				],
+			},
+			{
+				cell_type: "code",
+				execution_count: 7,
+				source: ["plot()\n"],
+				outputs: [
+					{
+						output_type: "display_data",
+						data: {
+							"image/png": "iVBORw0KGgoAAAANSUhEUgAA",
+							"text/html": "<img src='plot.png' />",
+						},
+						metadata: {
+							"image/png": {
+								height: 600,
+								width: 800,
+							},
+						},
+					},
+				],
+			},
+		],
+	});
+}
+
+describe("isNotebook", () => {
+	test("detects .ipynb path", () => {
+		expect(isNotebook("/tmp/analysis.ipynb")).toBe(true);
+		expect(isNotebook("/tmp/analysis.IPYNB")).toBe(true);
+		expect(isNotebook("/tmp/script.py")).toBe(false);
+	});
+});
+
+describe("parseNotebook", () => {
+	test("parses notebook cells and language", () => {
+		const parsed = parseNotebook(createSampleNotebook());
+		expect(parsed.language).toBe("python");
+		expect(parsed.cells).toHaveLength(4);
+		expect(parsed.cells[0]?.cell_type).toBe("markdown");
+		expect(parsed.cells[1]?.cell_type).toBe("code");
+		expect(parsed.cells[1]?.execution_count).toBe(5);
+		expect(parsed.cells[1]?.outputs?.[0]?.output_type).toBe("stream");
+	});
+
+	test("throws NotebookParseError for invalid JSON", () => {
+		expect(() => parseNotebook("not-json")).toThrow(NotebookParseError);
+	});
+
+	test("throws NotebookParseError when cells are missing", () => {
+		expect(() => parseNotebook(JSON.stringify({ metadata: {} }))).toThrow("missing cells array");
+	});
+});
+
+describe("formatNotebookOutput", () => {
+	test("formats code cells, outputs, errors, and image placeholders", () => {
+		const parsed = parseNotebook(createSampleNotebook());
+		const output = formatNotebookOutput(parsed);
+
+		expect(output).toContain("[Notebook: python | 4 cells");
+		expect(output).toContain("Cell 2 [code]");
+		expect(output).toContain("# [5]");
+		expect(output).toContain("```python");
+		expect(output).toContain("[Output 1: stream]");
+		expect(output).toContain("hello");
+		expect(output).toContain("[Output 1: error]");
+		expect(output).toContain("ZeroDivisionError: division by zero");
+		expect(output).toContain("[Image output: PNG 800x600]");
+		expect(output).toContain("[HTML output]");
+		expect(output).not.toContain("iVBORw0KGgoAAAANSUhEUgAA");
+	});
+});
+
+describe("summarizeNotebookCounts", () => {
+	test("returns code/markdown/raw/output totals", () => {
+		const parsed = parseNotebook(createSampleNotebook());
+		const counts = summarizeNotebookCounts(parsed);
+
+		expect(counts.codeCells).toBe(3);
+		expect(counts.markdownCells).toBe(1);
+		expect(counts.rawCells).toBe(0);
+		expect(counts.outputCount).toBe(3);
+	});
+});

package/extensions/read-tool-enhanced/extension.json

@@ -1,8 +1,8 @@
 {
 	"name": "read-tool-enhanced",
 	"version": "0.3.0",
-	"description": "Enhanced read tool with live truncated preview, compact summary, and PDF text extraction",
-	"whenToUse": "Use when you need improved `read` previews, truncation, and PDF extraction.",
+	"description": "Enhanced read tool with live truncated preview plus PDF and notebook extraction",
+	"whenToUse": "Use when you need improved `read` previews, truncation, and PDF/notebook extraction.",
 	"capabilities": {
 		"tools": ["read"],
 		"events": ["context", "session_start"]
@@ -14,8 +14,8 @@
 		"subprocess": false
 	},
 	"category": "utility",
-	"tags": ["context", "optimization", "display", "pdf"],
-	"files": ["index.ts", "pdf.ts"],
+	"tags": ["context", "optimization", "display", "pdf", "notebook"],
+	"files": ["index.ts", "notebook.ts", "pdf.ts"],
 	"relationships": [
 		{
 			"name": "tool-display",