pi-thread-engine 0.4.7 → 0.4.9

package/docs/HELLO_PYTHON.md

@@ -0,0 +1,68 @@
+# Python `hello_world()` Utility
+
+> A lightweight Python entry point for pi-thread-engine — useful for
+> Pi extension scripts that prefer Python over TypeScript.
+
+## Purpose
+
+Mirrors the TypeScript `helloWorld()` function (`src/hello.ts`) as a
+simple verification utility. Calling `hello_world()` returns the
+canonical greeting string `"Hello, World!"` with zero side effects.
+
+## Usage
+
+### Import
+
+```python
+from scripts.hello import hello_world
+
+greeting = hello_world()
+print(greeting)  # Hello, World!
+```
+
+### CLI invocation
+
+```bash
+python scripts/hello.py
+# Hello, World!
+```
+
+## Tests
+
+```bash
+python -m unittest scripts/test_hello.py -v
+```
+
+Expected output:
+
+```
+test_returns_hello_world_string (scripts.test_hello.TestHelloWorld.test_returns_hello_world_string)
+hello_world() should return exactly 'Hello, World!'. ... ok
+test_returns_string_type (scripts.test_hello.TestHelloWorld.test_returns_string_type)
+hello_world() should return a str instance. ... ok
+
+----------------------------------------------------------------------
+Ran 2 tests in 0.000s
+
+OK
+```
+
+## Implementation
+
+| Aspect | Detail |
+|--------|--------|
+| **File** | `scripts/hello.py` |
+| **Function** | `hello_world() -> str` |
+| **Return value** | `"Hello, World!"` |
+| **Framework** | Python 3 (stdlib only) |
+| **Test framework** | `unittest` (stdlib) |
+| **Test file** | `scripts/test_hello.py` |
+
+## Integration
+
+The Python test is integrated into the project's test suite via
+`scripts/test.sh` (step 4). Run the full suite with:
+
+```bash
+bash scripts/test.sh
+```

package/extensions/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { Type, type TUnsafe } from "@sinclair/typebox";
 import { Text } from "@mariozechner/pi-tui";
 
@@ -21,6 +21,7 @@ import type { Thread, ThreadType, Story, StoryPhase } from "../src/core/types.js
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "fs";
 import { join, resolve } from "path";
 import { createWorktree, removeWorktree, listWorktrees, pushWorktreeChanges, cleanupAll, isGitRepo, branchName, findRepoRoot } from "../src/core/worktree.js";
+import { helloWorld } from "../src/hello-world.js";
 
 // ── Export helper ───────────────────────────────────────────
 function exportThread(id: string, r: ThreadRegistry, cwd: string): string | null {
@@ -55,7 +56,11 @@ export default function (pi: ExtensionAPI) {
 		const threads = registry.all().filter((t) => t.state !== "killed");
 		const stories = registry.allStories();
 		if (threads.length > 0 || stories.length > 0) {
-			pi.appendEntry("pi-threads-state", { threads, stories, timestamp: Date.now() });
+			try {
+				pi.appendEntry("pi-threads-state", { threads, stories, timestamp: Date.now() });
+			} catch {
+				// Extension contexts can go stale after session replacement; persistence is best-effort.
+			}
 		}
 	}
 
@@ -81,8 +86,10 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Status bar ───────────────────────────────────────────────
 
+	let clearStatusHandler: (() => void) | undefined;
 	pi.on("session_start", async (_event, ctx) => {
-		registry.on(() => {
+		clearStatusHandler?.();
+		clearStatusHandler = registry.on(() => {
 			const running = registry.byState("running");
 			const stories = registry.allStories().filter((s) => s.state === "executing" || s.state === "planning");
 			const parts: string[] = [];
@@ -99,7 +106,11 @@ export default function (pi: ExtensionAPI) {
 				);
 			}
 
-			ctx.ui.setStatus("pi-threads", parts.length > 0 ? parts.join(" ") : undefined);
+			try {
+				ctx.ui.setStatus("pi-threads", parts.length > 0 ? parts.join(" ") : undefined);
+			} catch {
+				// Status updates are best-effort; command/session contexts may go stale.
+			}
 		});
 	});
 
@@ -125,6 +136,7 @@ export default function (pi: ExtensionAPI) {
 		return tasks;
 	}
 
+
 	function stateIcon(state: string): string {
 		switch (state) {
 			case "running": return "⟳";
@@ -138,16 +150,54 @@ export default function (pi: ExtensionAPI) {
 
 	function typeIcon(type: string): string {
 		switch (type) {
+			case "base": return "•";
 			case "parallel": return "⫘";
 			case "chained": return "⟶";
 			case "fusion": return "⊕";
 			case "meta": return "◎";
 			case "long": return "∞";
 			case "zero": return "⊘";
+			case "worktree": return "🌳";
+			case "plan": return "⌁";
+			case "scheduled": return "⏰";
 			default: return "·";
 		}
 	}
 
+	async function openDashboard(ctx: ExtensionCommandContext) {
+		await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+			const dashboard = createDashboard(
+				registry,
+				theme,
+				() => done(),
+				(id) => {
+					registry.kill(id);
+					ctx.ui.notify(`Killed ${id}`, "warning");
+					tui.requestRender();
+				},
+				(id) => {
+					const t = registry.get(id);
+					if (t) {
+						const preview = t.tasks.map((tk) => `${tk.id}: ${tk.result?.slice(0, 100) ?? tk.error ?? "(pending)"}`).join("\n");
+						ctx.ui.notify(`Thread ${id} results:\n${preview}`, "info");
+					}
+				},
+				(id, message) => {
+					executor.injectReply(id, message);
+					ctx.ui.notify(`Replied to ${id}: ${message.slice(0, 50)}...`, "info");
+					tui.requestRender();
+				},
+				(id) => { const p = exportThread(id, registry, ctx.cwd); if (p) ctx.ui.notify(`Exported to ${p}`, "info"); }
+			);
+
+			return {
+				render: (w: number) => dashboard.render(w),
+				invalidate: () => dashboard.invalidate(),
+				handleInput: (data: string) => { dashboard.handleInput(data); tui.requestRender(); },
+			};
+		});
+	}
+
 	// ── /threads — unified TUI dashboard ─────────────────────────
 
 	pi.registerCommand("threads", {
@@ -241,69 +291,21 @@ export default function (pi: ExtensionAPI) {
 				}
 				const ts = new Date().toISOString().slice(0, 19).replace(/[T:]/g, "-");
 				const fn = "threads-" + ts + ".md";
-				const outPath = require("path").join(ctx.cwd, fn);
-				require("fs").writeFileSync(outPath, md.join("\n"), "utf8");
+				const outPath = join(ctx.cwd, fn);
+				writeFileSync(outPath, md.join("\n"), "utf8");
 				ctx.ui.notify("Exported to " + outPath, "info");
 				return;
 			}
 
-			// Default: open interactive TUI dashboard
-			// ── /agents alias (Claude-style muscle memory) ──────────────
-			pi.registerCommand("agents", {
-				description: "Alias for /threads — Claude-style Agent View dashboard",
-				handler: async (a, c) => {
-					// Forward to /threads
-					await ctx.ui.custom<void>((tui, theme, _kb, done) => {
-						const dashboard = createDashboard(
-							registry,
-							theme,
-							() => done(),
-							(id) => { registry.kill(id); ctx.ui.notify(`Killed ${id}`, "warning"); tui.requestRender(); },
-							(id) => { const t = registry.get(id); if (t) { ctx.ui.notify(`Thread ${id}: ${t.tasks.map((tk) => `${tk.id}: ${tk.result?.slice(0,100) ?? tk.error ?? "(pending)"}`).join("\n")}`, "info"); } },
-							(id, message) => { executor.injectReply(id, message); ctx.ui.notify(`Replied to ${id}: ${message.slice(0, 50)}...`, "info"); tui.requestRender(); },
-							(id) => { const p = exportThread(id, registry, ctx.cwd); if (p) ctx.ui.notify(`Exported to ${p}`, "info"); }
-						);
-						return { render: (w: number) => dashboard.render(w), invalidate: () => dashboard.invalidate(), handleInput: (data: string) => { dashboard.handleInput(data); tui.requestRender(); } };
-					});
-				},
-			});
-			// ── End /agents alias ───────────────────────────────────────
-
-			await ctx.ui.custom<void>((tui, theme, _kb, done) => {
-				const dashboard = createDashboard(
-					registry,
-					theme,
-					() => done(),
-					(id) => {
-						registry.kill(id);
-						ctx.ui.notify(`Killed ${id}`, "warning");
-						tui.requestRender();
-					},
-					(id) => {
-						const t = registry.get(id);
-						if (t) {
-							const preview = t.tasks.map((tk) => `${tk.id}: ${tk.result?.slice(0, 100) ?? tk.error ?? "(pending)"}`).join("\n");
-							ctx.ui.notify(`Thread ${id} results:\n${preview}`, "info");
-						}
-					},
-					(id, message) => {
-						// Inline reply — send message to blocked thread
-						executor.injectReply(id, message);
-						ctx.ui.notify(`Replied to ${id}: ${message.slice(0, 50)}...`, "info");
-						tui.requestRender();
-					},
-					(id) => { const p = exportThread(id, registry, ctx.cwd); if (p) ctx.ui.notify(`Exported to ${p}`, "info"); }
-				);
-
-				return {
-					render: (w: number) => dashboard.render(w),
-					invalidate: () => dashboard.invalidate(),
-					handleInput: (data: string) => { dashboard.handleInput(data); tui.requestRender(); },
-				};
-			});
+			await openDashboard(ctx);
 		},
 	});
 
+	pi.registerCommand("agents", {
+		description: "Alias for /threads — Claude-style Agent View dashboard",
+		handler: async (_args, ctx) => openDashboard(ctx),
+	});
+
 	// ── /pthread — parallel via subagent ─────────────────────────
 
 	pi.registerCommand("pthread", {
@@ -321,19 +323,24 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	// ── /cthread — chained via subagent ──────────────────────────
+	// ── /cthread — chained with human checkpoints ─────────────────
 
 	pi.registerCommand("cthread", {
-		description: 'C-Thread: sequential phases via subagent chain. Usage: /cthread "phase 1" "phase 2"',
+		description: 'C-Thread: sequential phases with human checkpoints. Usage: /cthread "phase 1" "phase 2"',
 		handler: async (args, ctx) => {
 			if (!args?.trim()) { ctx.ui.notify('Usage: /cthread "phase 1" "phase 2"', "error"); return; }
 			const phases = parseTaskArgs(args);
 			if (phases.length < 2) { ctx.ui.notify("Need at least 2 phases", "error"); return; }
 
-			const thread = registry.create("chained", `Chain: ${phases.length} phases`, phases, { cwd: ctx.cwd, backend: "subagent" });
+			const thread = registry.create("chained", `Chain: ${phases.length} phases`, phases, { cwd: ctx.cwd, backend: "native" });
 
-			ctx.ui.notify(`🧵 C-Thread ${thread.id}: ${phases.length} phases via subagent chain...`, "info");
-			executor.dispatch(thread);
+			ctx.ui.notify(`🧵 C-Thread ${thread.id}: ${phases.length} phases with checkpoints...`, "info");
+			executor.dispatch(thread, {
+				onCheckpoint: async (phase, task) => ctx.ui.confirm(
+					"C-Thread checkpoint",
+					`Phase ${phase} complete. Continue to phase ${phase + 1}: ${task.label}?`
+				),
+			});
 		},
 	});
 
@@ -472,10 +479,10 @@ export default function (pi: ExtensionAPI) {
 	// ── /wthread — worktree isolation (port from Grok CLI) ────
 
 	pi.registerCommand("wthread", {
-		description: 'W-Thread: run task in isolated git worktree. Usage: /wthread "task" or /wthread list or /wthread cleanup',
+		description: 'W-Thread: run task in isolated git worktree. Usage: /wthread "task" or /wthread list, push, discard, cleanup',
 		handler: async (args, ctx) => {
 			if (!args?.trim()) {
-				ctx.ui.notify('Usage: /wthread "task" | /wthread list | /wthread cleanup', "error");
+				ctx.ui.notify('Usage: /wthread "task" | /wthread list | /wthread push <id> [message] | /wthread discard <id> | /wthread cleanup', "error");
 				return;
 			}
 
@@ -501,7 +508,8 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			if (sub === "push" && parts.length >= 2) {
+			if (sub === "push") {
+				if (parts.length < 2) { ctx.ui.notify('Usage: /wthread push <id> [message]', "error"); return; }
 				const threadId = parts[1];
 				const msg = parts.slice(2).join(" ") || undefined;
 				const ok = pushWorktreeChanges(ctx.cwd, threadId, msg);
@@ -509,6 +517,14 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			if (sub === "discard" || sub === "remove") {
+				if (parts.length < 2) { ctx.ui.notify('Usage: /wthread discard <id>', "error"); return; }
+				const threadId = parts[1];
+				const ok = removeWorktree(ctx.cwd, threadId);
+				ctx.ui.notify(ok ? `Discarded ${threadId} worktree` : "Discard failed", ok ? "info" : "error");
+				return;
+			}
+
 			// Default: create worktree and run task
 			if (!isGitRepo(ctx.cwd)) { ctx.ui.notify("Not in a git repo — can't create worktree", "error"); return; }
 
@@ -778,6 +794,16 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// ── /hello — Greeting command ───────────────────────────────
+
+	pi.registerCommand("hello", {
+		description: 'Say hello. Usage: /hello [name]',
+		handler: async (args, ctx) => {
+			const name = args?.trim() || undefined;
+			ctx.ui.notify(helloWorld(name), "info");
+		},
+	});
+
 	// ── LLM-callable tools ───────────────────────────────────────
 
 	pi.registerTool({
@@ -785,18 +811,19 @@ export default function (pi: ExtensionAPI) {
 		label: "Thread Spawn",
 		description: [
 			"Spawn a thread. Types:",
+			"- base: one prompt -> tool calls -> review (native)",
 			"- parallel: N independent tasks in parallel (via subagent)",
-			"- chained: sequential phases with checkpoints (via subagent)",
-			"- meta: scout→plan→build→review pipeline (via subagent)",
+			"- chained: sequential phases with human checkpoints (native)",
+			"- meta: scout -> plan -> build -> review pipeline (via subagent)",
 			"- fusion: same prompt to N agents/models, compare results (native, UNIQUE)",
 			"- zero: autonomous + verification command gate (native, UNIQUE)",
 			"- long: extended autonomous run (native)",
-			"- worktree: run in isolated git worktree (native, port from Grok CLI)",
-			"- plan: structured plan→approve→execute gate (native, port from Grok CLI)",
-			"- scheduled: recurring scheduled task (native, port from Grok CLI)",
+			"- worktree: run in isolated git worktree (native, extension beyond article)",
+			"- plan: structured plan -> approve -> execute gate (native, extension beyond article)",
+			"- scheduled: recurring scheduled task (native, extension beyond article)",
 		].join("\n"),
 		parameters: Type.Object({
-			type: StringEnum(["parallel", "fusion", "chained", "meta", "long", "zero", "worktree", "plan", "scheduled"] as const),
+			type: StringEnum(["base", "parallel", "fusion", "chained", "meta", "long", "zero", "worktree", "plan", "scheduled"] as const),
 			prompts: Type.Array(Type.String(), { description: "Task prompts" }),
 			models: Type.Optional(Type.Array(Type.String(), { description: "Models for fusion (e.g. ['anthropic/claude-sonnet-4', 'google/gemini-2.5-pro'])" })),
 			count: Type.Optional(Type.Number({ description: "Agent count for fusion (default 3)" })),
@@ -817,8 +844,9 @@ export default function (pi: ExtensionAPI) {
 				taskPrompts = [prompts[0]]; // Meta delegates to subagent chain internally
 			}
 
-			// Auto-select backend
-			const backend = backendOverride ?? (type === "fusion" || type === "zero" || type === "long" ? "native" : "subagent");
+			// Auto-select backend: P/B use subagents; C/F/L/Z and extension types run natively.
+			const nativeTypes = new Set(["base", "chained", "fusion", "zero", "long", "worktree", "plan", "scheduled"]);
+			const backend: import("../src/core/types.js").ExecutionBackend = (backendOverride as import("../src/core/types.js").ExecutionBackend) ?? (nativeTypes.has(String(type)) ? "native" as const : "subagent" as const);
 
 			const label = type === "fusion"
 				? `Fusion: ${prompts[0]?.slice(0, 40)}`
@@ -833,7 +861,12 @@ export default function (pi: ExtensionAPI) {
 			});
 
 			// Dispatch (async — runs in background)
-			executor.dispatch(thread);
+			executor.dispatch(thread, type === "chained" ? {
+				onCheckpoint: async (phase, task) => ctx.ui.confirm(
+					"C-Thread checkpoint",
+					`Phase ${phase} complete. Continue to phase ${phase + 1}: ${task.label}?`
+				),
+			} : undefined);
 
 			const modelInfo = models ? ` Models: ${models.join(", ")}` : "";
 			const verifyInfo = verify ? ` Verify: ${verify}` : "";
@@ -847,7 +880,7 @@ export default function (pi: ExtensionAPI) {
 				details: { threadId: thread.id, type, taskCount: taskPrompts.length, backend },
 			};
 		},
-		renderCall(args, theme) {
+		renderCall(args: any, theme: any) {
 			return new Text(
 				theme.fg("toolTitle", theme.bold("thread_spawn ")) +
 					theme.fg("accent", args.type) +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-thread-engine",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Thread-Based Engineering for pi — all 7 thread types + stories + fusion + zero-touch + TUI dashboard. Based on @IndyDevDan framework from agenticengineer.com.",
   "type": "module",
   "license": "MIT",
@@ -21,22 +21,31 @@
   "pi": {
     "extensions": [
       "./extensions/index.ts"
-    ]
+    ],
+    "commands": ["threads","agents","pthread","cthread","bthread","fthread","zthread","lthread","wthread","plan","tloop","story","stories","hello"],
+    "tools": ["thread_spawn","thread_status","thread_kill"]
   },
   "files": [
+    "_lib/",
     "extensions/",
     "src/",
     "README.md",
     "PLAN.md",
     "docs/"
   ],
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.73.0",
-    "@mariozechner/pi-tui": ">=0.73.0",
-    "@mariozechner/pi-ai": ">=0.73.0",
+    "@earendil-works/pi-ai": ">=0.73.0",
+    "@earendil-works/pi-coding-agent": ">=0.73.0",
+    "@earendil-works/pi-tui": ">=0.73.0",
     "@sinclair/typebox": "^0.34.48"
   }
 }

package/src/core/executor.ts

@@ -17,15 +17,22 @@ export class ThreadExecutor {
 
 	// ── Native execution (pi -p) ────────────────────────────────
 
+	private async execPi(args: string[], opts: { cwd: string; timeout: number }) {
+		if (process.platform === "win32") {
+			return this.pi.exec("cmd.exe", ["/d", "/s", "/c", "pi", ...args], opts);
+		}
+		return this.pi.exec("pi", args, opts);
+	}
+
 	private async runTaskNative(thread: Thread, task: ThreadTask): Promise<void> {
 		const cwd = thread.config.cwd ?? process.cwd();
 		this.registry.startTask(thread.id, task.id);
 
 		try {
-			const args = ["-p", task.prompt];
+			const args = ["--no-session", "--no-extensions", "--no-skills", "--no-context-files", "-p", task.prompt];
 			if (task.model) args.unshift("-m", task.model);
 
-			const result = await this.pi.exec("pi", args, {
+			const result = await this.execPi(args, {
 				cwd,
 				timeout: 10 * 60 * 1000,
 			});
@@ -226,7 +233,7 @@ export class ThreadExecutor {
 		this.registry.startThread(thread.id);
 
 		try {
-			const { createWorktree, removeWorktree, findRepoRoot, pushWorktreeChanges } = await import("./worktree.js");
+			const { createWorktree, findRepoRoot } = await import("./worktree.js");
 			const repoPath = findRepoRoot(cwd);
 
 			if (!repoPath) {
@@ -245,7 +252,7 @@ export class ThreadExecutor {
 
 			// Run the task inside the worktree using pi -p
 			try {
-				const result = await this.pi.exec("pi", ["-p", task.prompt], {
+				const result = await this.execPi(["--no-session", "--no-extensions", "--no-skills", "--no-context-files", "-p", task.prompt], {
 					cwd: wt.path,
 					timeout: 30 * 60 * 1000, // 30 min max
 				});
@@ -267,8 +274,7 @@ export class ThreadExecutor {
 				this.registry.failTask(thread.id, task.id, err.message ?? String(err));
 			}
 
-			// Always clean up worktree after execution
-			removeWorktree(cwd, thread.id);
+			// Preserve the worktree/branch for explicit /wthread push, discard, or cleanup.
 		} catch (err: any) {
 			this.registry.failTask(thread.id, thread.tasks[0].id, err.message ?? String(err));
 		}

package/src/core/registry.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { ThreadRegistry } from "./registry.js";
+
+describe("ThreadRegistry kill semantics", () => {
+  it("does not resurrect killed threads when async work completes late", () => {
+    const registry = new ThreadRegistry();
+    const thread = registry.create("base", "late finish", ["prompt"], { backend: "native" });
+
+    registry.startThread(thread.id);
+    registry.startTask(thread.id, thread.tasks[0].id);
+    registry.kill(thread.id);
+    registry.completeTask(thread.id, thread.tasks[0].id, "late result");
+
+    expect(thread.state).toBe("killed");
+    expect(thread.tasks[0].state).toBe("killed");
+    expect(thread.tasks[0].result).toBeUndefined();
+  });
+
+  it("does not resurrect killed threads when async work fails late", () => {
+    const registry = new ThreadRegistry();
+    const thread = registry.create("base", "late failure", ["prompt"], { backend: "native" });
+
+    registry.startThread(thread.id);
+    registry.startTask(thread.id, thread.tasks[0].id);
+    registry.kill(thread.id);
+    registry.failTask(thread.id, thread.tasks[0].id, "late error");
+
+    expect(thread.state).toBe("killed");
+    expect(thread.tasks[0].state).toBe("killed");
+    expect(thread.tasks[0].error).toBeUndefined();
+  });
+});