diffing 0.16.0 → 0.16.1

package/extensions/pi/index.ts

@@ -11,17 +11,28 @@
  *    `[Skill conflicts]` banner appears when pi runs inside the diffing repo.
  *
  * All tool executions spawn the `diffing` CLI in the consumer repo (ctx.cwd).
- * Install: `pi install git:github.com/ahmedragab20/diffing`, or symlink this
+ * Install: `pi install npm:diffing` (published on npm),
+ * `pi install git:github.com/ahmedragab20/diffing`, or symlink this
  * directory into `~/.pi/agent/extensions/diffing`.
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import {
+	existsSync,
+	lstatSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	symlinkSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -134,12 +145,12 @@ function describe(result: RunResult, command: string): string {
 		return out || "(no output)";
 	}
 	const err = result.stderr.trim();
-	const hint =
-		result.exitCode === 127
-			? "\n\n`diffing` was not found on PATH. Install it with `npm i -g diffing` or run `diffing setup`."
-			: result.exitCode === 3
-				? "\n\nNo diffing server is running for this repo. Start one with `diffing` (or the diffing_start_review tool)."
-				: "";
+	let hint = "";
+	if (result.exitCode === 127) {
+		hint = `\n\n\`diffing\` was not found on PATH (ran: diffing ${command}). Install it with \`npm i -g diffing\` or run \`diffing setup\`.`;
+	} else if (result.exitCode === 3) {
+		hint = `\n\nNo diffing server is running for this repo (ran: diffing ${command}). Start one with \`diffing\` (or the diffing_start_review tool).`;
+	}
 	return err ? `${err}${hint}` : `exit code ${result.exitCode}${hint}`;
 }
 
@@ -179,7 +190,10 @@ async function refreshStatus(ctx: ExtensionContext): Promise<void> {
 		const sessions = await activeSessions(ctx.cwd);
 		const active = sessions.find((s) => s.active) ?? sessions[0];
 		if (active) {
-			ctx.ui.setStatus("diffing", `diffing: ${active.mode ?? "session"} — ${active.url ?? ""}`);
+			ctx.ui.setStatus(
+				"diffing",
+				`diffing: ${active.mode ?? "session"} — ${active.url ?? ""}`,
+			);
 		} else {
 			ctx.ui.setStatus("diffing", "diffing: no server");
 		}
@@ -209,7 +223,9 @@ function findGitRepoRoot(startDir: string): string | null {
 
 function isDiffingRoot(dir: string): boolean {
 	try {
-		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { name?: string };
+		const pkg = JSON.parse(
+			readFileSync(join(dir, "package.json"), "utf-8"),
+		) as { name?: string };
 		if (pkg.name !== "diffing") return false;
 		return existsSync(join(dir, SKILLS_REL));
 	} catch {
@@ -262,7 +278,11 @@ function selfHealSkillLinks(canonical: string): void {
 
 function spawnDetachedReview(cwd: string, args: string[]): void {
 	try {
-		const child = spawn("diffing", args, { cwd, stdio: "ignore", detached: true });
+		const child = spawn("diffing", args, {
+			cwd,
+			stdio: "ignore",
+			detached: true,
+		});
 		child.unref();
 	} catch {
 		// surfaced by the URL poll below
@@ -279,7 +299,12 @@ async function ensureReviewUrl(
 	const existing = await diffingUrl(cwd);
 	if (existing && reuse) return { url: existing, reused: true };
 	if (existing && !reuse) return { url: existing, reused: true };
-	spawnDetachedReview(cwd, ["--web", "--no-open", "--skip-setup", ...extraArgs]);
+	spawnDetachedReview(cwd, [
+		"--web",
+		"--no-open",
+		"--skip-setup",
+		...extraArgs,
+	]);
 	const deadline = Date.now() + REVIEW_START_TIMEOUT_MS;
 	for (;;) {
 		if (signal?.aborted) break;
@@ -366,20 +391,33 @@ export default function (pi: ExtensionAPI) {
 				}),
 			),
 			reuse: Type.Optional(
-				Type.Boolean({ description: "Reuse the active session if one is running. Default: true.", default: true }),
+				Type.Boolean({
+					description:
+						"Reuse the active session if one is running. Default: true.",
+					default: true,
+				}),
 			),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			try {
 				const extra = params.prRef ? ["--gh-pr", params.prRef] : [];
-				const { url, reused } = await ensureReviewUrl(ctx.cwd, extra, params.reuse ?? true, signal);
+				const { url, reused } = await ensureReviewUrl(
+					ctx.cwd,
+					extra,
+					params.reuse ?? true,
+					signal,
+				);
 				await refreshStatus(ctx);
+				return textResult(`Review ${reused ? "reused" : "started"}: ${url}`, {
+					url,
+					reused,
+					mode: params.prRef ? "gh-pr" : "web",
+				});
+			} catch (error) {
 				return textResult(
-					`Review ${reused ? "reused" : "started"}: ${url}`,
-					{ url, reused, mode: params.prRef ? "gh-pr" : "web" },
+					error instanceof Error ? error.message : String(error),
+					{ started: false },
 				);
-			} catch (error) {
-				return textResult(error instanceof Error ? error.message : String(error), { started: false });
 			}
 		},
 	});
@@ -391,9 +429,17 @@ export default function (pi: ExtensionAPI) {
 			"Snapshot the current review comments as XML (or JSON). Use --open to see only unresolved threads. Parse the returned XML to act on feedback.",
 		parameters: Type.Object({
 			open: Type.Optional(
-				Type.Boolean({ description: "Only include open (unresolved) comment threads. Default: true.", default: true }),
+				Type.Boolean({
+					description:
+						"Only include open (unresolved) comment threads. Default: true.",
+					default: true,
+				}),
+			),
+			format: Type.Optional(
+				StringEnum(["xml", "json", "md"] as const, {
+					description: "Output format. Default: xml.",
+				}),
 			),
-			format: Type.Optional(StringEnum(["xml", "json", "md"] as const, { description: "Output format. Default: xml." })),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const args = ["comments"];
@@ -411,16 +457,33 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "diffing_reply",
 		label: "Diffing Reply",
-		description: "Append a reply to an existing comment thread by id. Answers questions; does not resolve.",
+		description:
+			"Append a reply to an existing comment thread by id. Answers questions; does not resolve.",
 		parameters: Type.Object({
-			commentId: Type.String({ description: "UUID of the comment thread to reply to." }),
+			commentId: Type.String({
+				description: "UUID of the comment thread to reply to.",
+			}),
 			body: Type.String({ description: "Markdown reply body." }),
-			model: Type.Optional(Type.String({ description: "Model name to attribute. Defaults to the active model." })),
+			model: Type.Optional(
+				Type.String({
+					description: "Model name to attribute. Defaults to the active model.",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
-			const result = await runDiffing(["reply", params.commentId, "-", "--model", modelName(ctx, params.model)], ctx.cwd, {
-				stdin: params.body,
-			});
+			const result = await runDiffing(
+				[
+					"reply",
+					params.commentId,
+					"-",
+					"--model",
+					modelName(ctx, params.model),
+				],
+				ctx.cwd,
+				{
+					stdin: params.body,
+				},
+			);
 			return textResult(describe(result, `diffing reply ${params.commentId}`), {
 				exitCode: result.exitCode,
 				stderr: result.stderr.trim() || undefined,
@@ -431,14 +494,20 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "diffing_resolve",
 		label: "Diffing Resolve",
-		description: "Mark a review comment thread resolved. Use after addressing a change request.",
-		parameters: Type.Object({ commentId: Type.String({ description: "UUID of the comment thread." }) }),
+		description:
+			"Mark a review comment thread resolved. Use after addressing a change request.",
+		parameters: Type.Object({
+			commentId: Type.String({ description: "UUID of the comment thread." }),
+		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const result = await runDiffing(["resolve", params.commentId], ctx.cwd);
-			return textResult(describe(result, `diffing resolve ${params.commentId}`), {
-				exitCode: result.exitCode,
-				stderr: result.stderr.trim() || undefined,
-			});
+			return textResult(
+				describe(result, `diffing resolve ${params.commentId}`),
+				{
+					exitCode: result.exitCode,
+					stderr: result.stderr.trim() || undefined,
+				},
+			);
 		},
 	});
 
@@ -446,13 +515,18 @@ export default function (pi: ExtensionAPI) {
 		name: "diffing_unresolve",
 		label: "Diffing Unresolve",
 		description: "Re-open a previously resolved comment thread.",
-		parameters: Type.Object({ commentId: Type.String({ description: "UUID of the comment thread." }) }),
+		parameters: Type.Object({
+			commentId: Type.String({ description: "UUID of the comment thread." }),
+		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const result = await runDiffing(["unresolve", params.commentId], ctx.cwd);
-			return textResult(describe(result, `diffing unresolve ${params.commentId}`), {
-				exitCode: result.exitCode,
-				stderr: result.stderr.trim() || undefined,
-			});
+			return textResult(
+				describe(result, `diffing unresolve ${params.commentId}`),
+				{
+					exitCode: result.exitCode,
+					stderr: result.stderr.trim() || undefined,
+				},
+			);
 		},
 	});
 
@@ -462,18 +536,35 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Post a live progress toast to the review UI so the human sees status while work is underway. Safe to call frequently.",
 		parameters: Type.Object({
-			message: Type.String({ description: "Progress message, e.g. 'Addressing L42…'." }),
-			pct: Type.Optional(Type.Number({ description: "Optional 0-100 completion percent." })),
-			model: Type.Optional(Type.String({ description: "Model name to attribute. Defaults to the active model." })),
+			message: Type.String({
+				description: "Progress message, e.g. 'Addressing L42…'.",
+			}),
+			pct: Type.Optional(
+				Type.Number({ description: "Optional 0-100 completion percent." }),
+			),
+			model: Type.Optional(
+				Type.String({
+					description: "Model name to attribute. Defaults to the active model.",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
-			const args = ["progress", "--message", params.message, "--model", modelName(ctx, params.model)];
+			const args = [
+				"progress",
+				"--message",
+				params.message,
+				"--model",
+				modelName(ctx, params.model),
+			];
 			if (params.pct !== undefined) args.push("--pct", String(params.pct));
 			const result = await runDiffing(args, ctx.cwd);
-			return textResult(describe(result, `diffing progress --message "${params.message}"`), {
-				exitCode: result.exitCode,
-				stderr: result.stderr.trim() || undefined,
-			});
+			return textResult(
+				describe(result, `diffing progress --message "${params.message}"`),
+				{
+					exitCode: result.exitCode,
+					stderr: result.stderr.trim() || undefined,
+				},
+			);
 		},
 	});
 
@@ -484,12 +575,19 @@ export default function (pi: ExtensionAPI) {
 			"Synchronously wait (long-poll) until the human releases the review ('Send to agent'), then return the comments XML. Exit code 2 (or a timeout) is an expected park signal — do not silent-loop; resume once the human says the review is ready.",
 		parameters: Type.Object({
 			timeout: Type.Optional(
-				Type.Number({ description: "Max seconds to block. Default: 60 (park beyond that).", default: 60 }),
+				Type.Number({
+					description: "Max seconds to block. Default: 60 (park beyond that).",
+					default: 60,
+				}),
 			),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const timeout = Math.min(Math.max(params.timeout ?? 60, 1), 600);
-			const result = await runDiffing(["await-review", "-t", String(timeout)], ctx.cwd, { signal });
+			const result = await runDiffing(
+				["await-review", "-t", String(timeout)],
+				ctx.cwd,
+				{ signal },
+			);
 			const parked = result.exitCode === 2;
 			if (parked) {
 				return textResult(
@@ -512,26 +610,52 @@ export default function (pi: ExtensionAPI) {
 			"Submit (or resubmit) a markdown plan for human review. Pass the plan as file (path) or body (inline text). Returns the plan id and review URL. Default handoff is async: share the URL, end the turn, act on the verdict when the human decides.",
 		parameters: Type.Object({
 			file: Type.Optional(
-				Type.String({ description: "Path to the plan markdown file. Use the body parameter instead to submit inline text." }),
+				Type.String({
+					description:
+						"Path to the plan markdown file. Use the body parameter instead to submit inline text.",
+				}),
+			),
+			body: Type.Optional(
+				Type.String({ description: "Inline plan markdown body." }),
+			),
+			title: Type.Optional(
+				Type.String({
+					description: "Display title. Defaults to the plan's first heading.",
+				}),
 			),
-			body: Type.Optional(Type.String({ description: "Inline plan markdown body." })),
-			title: Type.Optional(Type.String({ description: "Display title. Defaults to the plan's first heading." })),
 			planId: Type.Optional(
-				Type.String({ description: "Resubmit a revised body for an existing plan id (bumps version, resets verdict)." }),
+				Type.String({
+					description:
+						"Resubmit a revised body for an existing plan id (bumps version, resets verdict).",
+				}),
+			),
+			model: Type.Optional(
+				Type.String({
+					description: "Authoring model. Defaults to the active model.",
+				}),
 			),
-			model: Type.Optional(Type.String({ description: "Authoring model. Defaults to the active model." })),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			let stdin: string | undefined;
 			let fileArg = params.file;
 			if (!fileArg) {
 				if (!params.body) {
-					return textResult("Provide either file (path) or body (inline plan markdown).", { submitted: false });
+					return textResult(
+						"Provide either file (path) or body (inline plan markdown).",
+						{ submitted: false },
+					);
 				}
 				fileArg = "-";
 				stdin = params.body;
 			}
-			const args = ["plan", "submit", fileArg, "--save-source", "--model", modelName(ctx, params.model)];
+			const args = [
+				"plan",
+				"submit",
+				fileArg,
+				"--save-source",
+				"--model",
+				modelName(ctx, params.model),
+			];
 			if (params.title) args.push("--title", params.title);
 			if (params.planId) args.push("--id", params.planId);
 			const result = await runDiffing(args, ctx.cwd, { signal, stdin });
@@ -559,12 +683,19 @@ export default function (pi: ExtensionAPI) {
 			"Synchronously wait until the human decides on the submitted plan, then return the <plan-review> XML with the verdict. Exit code 2 is an expected park signal — do not silent-loop.",
 		parameters: Type.Object({
 			timeout: Type.Optional(
-				Type.Number({ description: "Max seconds to block. Default: 60 (park beyond that).", default: 60 }),
+				Type.Number({
+					description: "Max seconds to block. Default: 60 (park beyond that).",
+					default: 60,
+				}),
 			),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const timeout = Math.min(Math.max(params.timeout ?? 60, 1), 600);
-			const result = await runDiffing(["plan", "await", "-t", String(timeout)], ctx.cwd, { signal });
+			const result = await runDiffing(
+				["plan", "await", "-t", String(timeout)],
+				ctx.cwd,
+				{ signal },
+			);
 			if (result.exitCode === 2) {
 				return textResult(
 					`No plan verdict within ${timeout}s (park). Share the plan URL and end your turn; run diffing_plan_await again when the human says the verdict is ready.`,
@@ -582,9 +713,12 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "diffing_plan_list",
 		label: "Diffing Plan List",
-		description: "List submitted plans for the current repo (id, decision, version, open comments, title).",
+		description:
+			"List submitted plans for the current repo (id, decision, version, open comments, title).",
 		parameters: Type.Object({
-			json: Type.Optional(Type.Boolean({ description: "Emit raw JSON instead of the table." })),
+			json: Type.Optional(
+				Type.Boolean({ description: "Emit raw JSON instead of the table." }),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const args = ["plan", "list"];
@@ -600,10 +734,15 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "diffing_plan_show",
 		label: "Diffing Plan Show",
-		description: "Show a single plan as <plan-review> XML (or raw JSON) including the verdict and open comments.",
+		description:
+			"Show a single plan as <plan-review> XML (or raw JSON) including the verdict and open comments.",
 		parameters: Type.Object({
-			planId: Type.Optional(Type.String({ description: "Plan id. Omit for the latest plan." })),
-			json: Type.Optional(Type.Boolean({ description: "Emit raw JSON instead of XML." })),
+			planId: Type.Optional(
+				Type.String({ description: "Plan id. Omit for the latest plan." }),
+			),
+			json: Type.Optional(
+				Type.Boolean({ description: "Emit raw JSON instead of XML." }),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const args = ["plan", "show"];
@@ -620,22 +759,37 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "diffing_plan_reply",
 		label: "Diffing Plan Reply",
-		description: "Reply to an inline plan comment (the owning plan is resolved automatically).",
+		description:
+			"Reply to an inline plan comment (the owning plan is resolved automatically).",
 		parameters: Type.Object({
 			commentId: Type.String({ description: "UUID of the plan comment." }),
 			body: Type.String({ description: "Markdown reply body." }),
-			model: Type.Optional(Type.String({ description: "Model name to attribute. Defaults to the active model." })),
+			model: Type.Optional(
+				Type.String({
+					description: "Model name to attribute. Defaults to the active model.",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const result = await runDiffing(
-				["plan", "reply", params.commentId, "-", "--model", modelName(ctx, params.model)],
+				[
+					"plan",
+					"reply",
+					params.commentId,
+					"-",
+					"--model",
+					modelName(ctx, params.model),
+				],
 				ctx.cwd,
 				{ stdin: params.body },
 			);
-			return textResult(describe(result, `diffing plan reply ${params.commentId}`), {
-				exitCode: result.exitCode,
-				stderr: result.stderr.trim() || undefined,
-			});
+			return textResult(
+				describe(result, `diffing plan reply ${params.commentId}`),
+				{
+					exitCode: result.exitCode,
+					stderr: result.stderr.trim() || undefined,
+				},
+			);
 		},
 	});
 
@@ -643,25 +797,36 @@ export default function (pi: ExtensionAPI) {
 		name: "diffing_plan_resolve",
 		label: "Diffing Plan Resolve",
 		description: "Mark a plan comment resolved.",
-		parameters: Type.Object({ commentId: Type.String({ description: "UUID of the plan comment." }) }),
+		parameters: Type.Object({
+			commentId: Type.String({ description: "UUID of the plan comment." }),
+		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
-			const result = await runDiffing(["plan", "resolve", params.commentId], ctx.cwd);
-			return textResult(describe(result, `diffing plan resolve ${params.commentId}`), {
-				exitCode: result.exitCode,
-				stderr: result.stderr.trim() || undefined,
-			});
+			const result = await runDiffing(
+				["plan", "resolve", params.commentId],
+				ctx.cwd,
+			);
+			return textResult(
+				describe(result, `diffing plan resolve ${params.commentId}`),
+				{
+					exitCode: result.exitCode,
+					stderr: result.stderr.trim() || undefined,
+				},
+			);
 		},
 	});
 
 	pi.registerTool({
 		name: "diffing_url",
 		label: "Diffing URL",
-		description: "Print the base URL of the active diffing review server for this repo, or report that none is running.",
+		description:
+			"Print the base URL of the active diffing review server for this repo, or report that none is running.",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			const url = await diffingUrl(ctx.cwd);
 			return textResult(
-				url ? url : "No diffing server running for this repo. Start one with diffing_start_review or `/diffing`.",
+				url
+					? url
+					: "No diffing server running for this repo. Start one with diffing_start_review or `/diffing`.",
 				{ url },
 			);
 		},
@@ -673,9 +838,19 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"List, select, or stop live diffing review sessions for this repo. use: retarget agent commands to a session id prefix. stop: graceful shutdown of a session.",
 		parameters: Type.Object({
-			action: Type.Optional(StringEnum(["list", "use", "stop"] as const, { description: "Action. Default: list." })),
-			value: Type.Optional(Type.String({ description: "Session id prefix (for use/stop), or 'active'/'all'." })),
-			json: Type.Optional(Type.Boolean({ description: "Emit JSON for list. Default: false." })),
+			action: Type.Optional(
+				StringEnum(["list", "use", "stop"] as const, {
+					description: "Action. Default: list.",
+				}),
+			),
+			value: Type.Optional(
+				Type.String({
+					description: "Session id prefix (for use/stop), or 'active'/'all'.",
+				}),
+			),
+			json: Type.Optional(
+				Type.Boolean({ description: "Emit JSON for list. Default: false." }),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const action = params.action ?? "list";
@@ -700,7 +875,11 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Probe the active GitHub PR review session: PR identity, head/base SHAs, patch size, and conversation/draft counts. Fails cleanly when no PR session is active.",
 		parameters: Type.Object({
-			json: Type.Optional(Type.Boolean({ description: "Emit raw JSON instead of human-readable output." })),
+			json: Type.Optional(
+				Type.Boolean({
+					description: "Emit raw JSON instead of human-readable output.",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const args = ["gh", "overview"];
@@ -719,15 +898,29 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Escape hatch: run any documented `diffing` agent subcommand with raw arguments. Examples: ['inspect','summary'], ['comment','edit',id,'--body','...'], ['gh','threads','--unresolved'], ['gh','reviews'], ['plan','versions',id], ['doctor'], ['mode']. Returns stdout + exit code; exit 3 means no server.",
 		parameters: Type.Object({
-			args: Type.Array(Type.String({ description: "Subcommand and arguments, e.g. ['inspect','summary']." })),
-			stdin: Type.Optional(Type.String({ description: "Optional text to pipe to the command's stdin (e.g. reply bodies)." })),
+			args: Type.Array(
+				Type.String({
+					description: "Subcommand and arguments, e.g. ['inspect','summary'].",
+				}),
+			),
+			stdin: Type.Optional(
+				Type.String({
+					description:
+						"Optional text to pipe to the command's stdin (e.g. reply bodies).",
+				}),
+			),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const args = params.args;
 			if (!Array.isArray(args) || args.length === 0) {
-				return textResult("Provide at least one subcommand argument.", { ran: false });
+				return textResult("Provide at least one subcommand argument.", {
+					ran: false,
+				});
 			}
-			const result = await runDiffing(args, ctx.cwd, { signal, stdin: params.stdin });
+			const result = await runDiffing(args, ctx.cwd, {
+				signal,
+				stdin: params.stdin,
+			});
 			return textResult(describe(result, `diffing ${args.join(" ")}`), {
 				exitCode: result.exitCode,
 				stderr: result.stderr.trim() || undefined,
@@ -747,7 +940,10 @@ export default function (pi: ExtensionAPI) {
 				await refreshStatus(ctx);
 				ctx.ui.notify(`diffing review: ${url}`, "info");
 			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				ctx.ui.notify(
+					error instanceof Error ? error.message : String(error),
+					"error",
+				);
 			}
 		},
 	});

package/extensions/pi/pi-modules.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ambient declarations for pi-bundled modules.
+ *
+ * The pi harness provides `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`
+ * and `typebox` at extension load time — they are intentionally NOT installed in
+ * this repository (keeps the product lockfile free of the pi runtime tree). These
+ * declarations let the extension typecheck standalone for editors/LSP; the
+ * authoritative types are the real packages resolved by pi at runtime.
+ */
+
+declare module "@earendil-works/pi-ai" {
+	export function StringEnum<T extends readonly string[]>(
+		values: T,
+		options?: { description?: string; default?: T[number] },
+	): { type: "string"; enum: T; description?: string; default?: T[number] };
+}
+
+declare module "@earendil-works/pi-coding-agent" {
+	export interface ExtensionContext {
+		cwd: string;
+		hasUI: boolean;
+		model?: { id: string; provider?: string };
+		ui: {
+			setStatus(id: string, text: string): void;
+			notify(
+				text: string,
+				level?: "info" | "error" | "success" | "warning",
+			): void;
+			setWidget?(id: string, lines: string[]): void;
+		};
+	}
+
+	export interface ToolResult {
+		content: { type: "text"; text: string }[];
+		details: Record<string, unknown>;
+	}
+
+	export interface ToolDefinition {
+		name: string;
+		label?: string;
+		description: string;
+		parameters: any;
+		execute(
+			toolCallId: string,
+			params: any,
+			signal: AbortSignal | undefined,
+			onUpdate: any,
+			ctx: ExtensionContext,
+		): Promise<ToolResult> | ToolResult;
+	}
+
+	export interface ExtensionAPI {
+		on(
+			event: string,
+			handler: (event: any, ctx: ExtensionContext) => any,
+		): void;
+		registerTool(definition: ToolDefinition): void;
+		registerCommand(
+			name: string,
+			definition: {
+				description?: string;
+				handler: (args: string | undefined, ctx: ExtensionContext) => any;
+			},
+		): void;
+	}
+}
+
+declare module "typebox" {
+	export const Type: any;
+}