@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/extensions/plan/tools/exit.ts

@@ -3,7 +3,7 @@
  *
  * It presents the saved plan for approval, then seeds the approved steps into
  * the todo list and finalizes the session goal: a `planning` goal becomes the
- * plan's own `## Goal`, and a session with no goal is offered the same. The
+ * plan's own `## Goal`, and a session with no goal is given the same. The
  * review loop and the browser lifecycle belong to `review.ts`; the nested writes
  * belong to `todo-seed.ts` and the goal tool.
  */
@@ -12,17 +12,21 @@ import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../../lib/format.ts";
+import { messageOf } from "../../../lib/errors.ts";
 import { lastGoal } from "../../../lib/goal-state.ts";
 import { GOAL_TOOL } from "../../../lib/tool-names.ts";
 import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine, moreHint } from "../../../lib/tui/tool.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
 import { feedbackSummary } from "../feedback.ts";
 import { mergeSummary, overCap, preview, verificationNote } from "../format.ts";
 import { sanitizePlanText } from "../plan-text.ts";
 import { planTitle, type StoredPlan } from "../plans.ts";
 import { reviewPlan } from "../review.ts";
+import { decideSplit, rosterCard, SPLIT_OFF_NOTE } from "../split.ts";
+import { writeTeam } from "../../../lib/plans/team.ts";
 import { EXIT_TOOL, SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
 import { goalSection, MAX_STEPS, planStepSummary } from "../steps.ts";
 import type { ExitPlanModeDetails } from "../types.ts";
@@ -30,11 +34,27 @@ import type { PlanWebReview } from "../web.ts";
 import { firstTextLine } from "./nested.ts";
 import { seedTodos } from "./todo-seed.ts";
 
+const PlanUnitParams = Type.Object({
+	name: Type.String({ description: "Lowercase slug; the owner session takes it as its label." }),
+	paths: Type.Array(Type.String(), { description: "Repository-relative path prefixes this unit owns." }),
+	test: Type.String({ description: "The command that proves the unit is done." }),
+	dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Units that must land first." })),
+	lead: Type.Optional(Type.Boolean({ description: "True for the one unit this session keeps." })),
+});
+
 const ExitPlanModeParams = Type.Object({
 	plan_path: Type.String({
 		description:
-			"Path to the plan file written by write_plan (absolute, or relative to the working directory). The user reviews this file.",
+			"Path to the plan file written by write_plan: the absolute path it returned, or the `~/…` form it displayed. A bare name resolves inside the plans directory. The user reviews this file.",
 	}),
+	units: Type.Optional(
+		Type.Array(PlanUnitParams, {
+			description:
+				"The plan's slices, when it has two or more independent ones the user will run in separate sessions. " +
+				"Only used when the plan.split setting is on; validation refuses an overlapping, looping, or oversized " +
+				"split before the review opens. Omit it to approve as one flow.",
+		}),
+	),
 });
 
 type ExitPlanModeArgs = Static<typeof ExitPlanModeParams>;
@@ -50,21 +70,16 @@ interface GoalOutcome {
 /**
  * Finalise the session goal from the approved plan.
  *
- * A `planning` goal needs no dialog — approving the plan *is* the decision — and a
- * session with no goal at all gets one confirm. A final goal (`active` or
- * `achieved`) is the user's own: approving ordinary work never rewrites it.
- * Recording runs through the goal tool, so validation and the widget stay goal's,
- * and no model turn is spent.
+ * Approving the plan *is* the decision, so neither a `planning` goal nor a
+ * session with none is asked again. A final goal (`active` or `achieved`) is the
+ * user's own: approving ordinary work never rewrites it. Recording runs through
+ * the goal tool, so validation and the widget stay goal's, and no model turn is
+ * spent.
  */
 async function finalizeGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOutcome> {
 	const objective = planObjective(plan);
 	const current = lastGoal(ctx.sessionManager.getBranch());
 	if (current !== null && current.status !== "planning") return { objective };
-	if (current === null) {
-		if (!ctx.hasUI) return { objective };
-		const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
-		if (!approved) return { objective };
-	}
 	const outcome = await ctx.executeTool(GOAL_TOOL, { objective, status: "active" });
 	const action = current === null ? "recorded" : "promoted";
 	return outcome.isError ? { objective, action, error: firstTextLine(outcome) } : { objective, action };
@@ -96,68 +111,71 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const planPath = (params as ExitPlanModeArgs).plan_path.trim();
+			const args = params as ExitPlanModeArgs;
+			const planPath = args.plan_path.trim();
 
 			if (!runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not in plan mode; there is no plan to approve." }],
-					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				return failedResult("Not in plan mode; there is no plan to approve.", {
+					approved: false,
+					plan: "",
+					planPath,
+				} satisfies ExitPlanModeDetails);
 			}
 
 			const file = await runtime.plans.read(ctx.cwd, planPath);
 			if (!file) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No plan file at "${planPath}". Save the plan with write_plan first, then pass the returned path.`,
-						},
-					],
-					details: { approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				return failedResult(
+					`No plan file at "${planPath}". Save the plan with write_plan first, then pass the returned path.`,
+					{ approved: false, plan: "", planPath } satisfies ExitPlanModeDetails,
+				);
 			}
 
 			const total = planStepSummary(file.content).total;
 			if (total > MAX_STEPS) {
 				// A hand-edited or older plan file can still be over the cap; refuse it here
 				// too, so approval never seeds a list it cannot hold in full.
-				return {
-					content: [
-						{
-							type: "text",
-							text: `${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
-						},
-					],
-					details: {
+				return failedResult(
+					`${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+					{
 						approved: false,
 						plan: file.content,
 						planPath: file.path,
 						relativePath: file.relativePath,
 					} satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				);
+			}
+
+			// The split is decided before the review opens, so a refused or rejected split
+			// never spends the user's review — and the screen can show what it approves.
+			const units = args.units?.map((unit) => ({
+				name: unit.name,
+				paths: [...unit.paths],
+				test: unit.test,
+				dependsOn: [...(unit.dependsOn ?? [])],
+				...(unit.lead ? { lead: true } : {}),
+			}));
+			const split = decideSplit(ctx.cwd, await runtime.plans.rootFor(ctx.cwd), units);
+			if (split.kind === "refused") {
+				return failedResult(`Refused: ${split.reason}`, {
+					approved: false,
+					plan: file.content,
+					planPath: file.path,
+					relativePath: file.relativePath,
+				} satisfies ExitPlanModeDetails);
 			}
+			const pending = split.kind === "team" ? split : undefined;
 
 			if (!ctx.hasUI) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No interactive UI is available to approve the plan. It is saved at ${file.relativePath}; present it and ask the user to approve it in their reply.`,
-						},
-					],
-					details: {
+				return failedResult(
+					`No interactive UI is available to approve the plan. It is saved at ${file.relativePath}; present it and ask the user to approve it in their reply.`,
+					{
 						approved: false,
 						plan: file.content,
 						planPath: file.path,
 						relativePath: file.relativePath,
 						unavailable: true,
 					} satisfies ExitPlanModeDetails,
-					isError: true,
-				};
+				);
 			}
 
 			// One decision, however the session is attached; `review.ts` owns the loop,
@@ -169,6 +187,7 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 				baselines: runtime,
 				plan: file,
 				signal,
+				...(pending === undefined ? {} : { split: { ...pending.team, verdict: pending.verdict } }),
 			});
 
 			if (decision.action === "refine") {
@@ -208,10 +227,56 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 					} satisfies ExitPlanModeDetails,
 				};
 			}
+			if (decision.action === "cancel") {
+				runtime.disable(ctx);
+				const shown = decision.plan.relativePath;
+				ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								"Plan mode is off and write access is restored. The plan was not approved and no steps were recorded. " +
+								`The plan file ${shown} remains if the user wants to review it later.`,
+						},
+					],
+					details: {
+						approved: false,
+						cancelled: true,
+						plan: decision.plan.content,
+						planPath: decision.plan.path,
+						relativePath: decision.plan.relativePath,
+					} satisfies ExitPlanModeDetails,
+				};
+			}
 
+			// The team becomes real here, never before: the section is what a joining
+			// session reads, so it appears only after the user approved the split. The
+			// write happens while plan mode is still on, so a failure leaves the session
+			// able to retry instead of approved-but-empty.
+			let approved = decision.plan;
+			if (pending !== undefined) {
+				try {
+					approved = await runtime.plans.write(ctx.cwd, {
+						title: planTitle(basename(decision.plan.path)),
+						content: writeTeam(decision.plan.content, { lead: pending.team.lead, units: pending.team.units }),
+						planPath: decision.plan.path,
+					});
+				} catch (writeError) {
+					return failedResult(
+						`The plan was approved but its team could not be written: ${messageOf(writeError)}. Plan mode is still on and no steps were seeded; fix the plan file and call exit_plan_mode again.`,
+						{
+							approved: false,
+							plan: decision.plan.content,
+							planPath: decision.plan.path,
+							relativePath: decision.plan.relativePath,
+						} satisfies ExitPlanModeDetails,
+					);
+				}
+			}
 			runtime.disable(ctx);
-			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
-			const goal = await finalizeGoal(ctx, decision.plan);
+			const { steps, merged, error } = await seedTodos(pi, ctx, approved.content);
+			const goal = await finalizeGoal(ctx, approved);
 			const listing =
 				steps.length > 0
 					? `\n\n${steps
@@ -238,19 +303,41 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 			const browserNote = decision.comments.length
 				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(decision.comments)}`
 				: "";
+			const splitNote =
+				pending === undefined
+					? split.kind === "off"
+						? `\n\n${SPLIT_OFF_NOTE}`
+						: ""
+					: `\n\n${rosterCard(pending.team, approved.path, pi.getSessionName())}\n\nWork only your own unit (${pending.team.lead}); the other units belong to the sessions the user starts.`;
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${verification}${goalNote}${listing}`,
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${approved.relativePath} is the source of truth; follow its steps.${browserNote}${splitNote}${tail}${verification}${goalNote}${listing}`,
 					},
 				],
 				details: {
 					approved: true,
-					plan: decision.plan.content,
-					planPath: decision.plan.path,
-					relativePath: decision.plan.relativePath,
+					plan: approved.content,
+					planPath: approved.path,
+					relativePath: approved.relativePath,
 					annotations: decision.comments.length > 0 ? decision.comments : undefined,
+					...(pending === undefined
+						? split.kind === "off"
+							? { splitOff: true }
+							: {}
+						: {
+								team: {
+									lead: pending.team.lead,
+									verdict: pending.verdict,
+									units: pending.team.units.map((unit) => ({
+										name: unit.name,
+										paths: unit.paths,
+										test: unit.test,
+										dependsOn: unit.dependsOn,
+									})),
+								},
+							}),
 				} satisfies ExitPlanModeDetails,
 			};
 		},
@@ -269,11 +356,13 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 			const details = outcome.details;
 			const heading = details.unavailable
 				? paint(theme, "warn", "No UI to approve the plan")
-				: details.approved
-					? paint(theme, "ok", `${GLYPHS.check} Plan approved`)
-					: details.refined
-						? paint(theme, "accent", "Refining the plan")
-						: paint(theme, "warn", "Plan not approved");
+				: details.cancelled
+					? paint(theme, "warn", "Plan mode off — plan not approved")
+					: details.approved
+						? paint(theme, "ok", `${GLYPHS.check} Plan approved`)
+						: details.refined
+							? paint(theme, "accent", "Refining the plan")
+							: paint(theme, "warn", "Plan not approved");
 			const extra =
 				details.refined && details.refinement
 					? `\n${paint(theme, "meta", `↳ ${sanitizePlanText(details.refinement)}`)}`

package/extensions/plan/tools/steps.ts

@@ -13,6 +13,7 @@ import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
+import { failedResult, textResult } from "../../../lib/tool-result.ts";
 import { describeUpdates, stepLabel } from "../format.ts";
 import { SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
 import { extractPlanSteps } from "../steps.ts";
@@ -66,39 +67,26 @@ export function registerSetPlanStepsTool(pi: ExtensionAPI, runtime: PlanRuntime)
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const args = params as SetPlanStepsArgs;
 			if (runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not while planning; refine the plan with write_plan instead." }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult("Not while planning; refine the plan with write_plan instead.", undefined);
 			}
 			try {
 				const plan = await runtime.plans.setSteps(ctx.cwd, args.plan_path, args.updates);
 				const steps = extractPlanSteps(plan.content);
 				const done = steps.filter((step) => step.status === "completed").length;
 				const todoNote = await mirrorTodos(ctx, args.updates);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `${describeUpdates(args.updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
-						},
-					],
-					details: {
+				return textResult(
+					`${describeUpdates(args.updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
+					{
 						path: plan.path,
 						relativePath: plan.relativePath,
 						updates: args.updates,
 						done,
 						total: steps.length,
 					} satisfies SetPlanStepsDetails,
-				};
+				);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return {
-					content: [{ type: "text", text: `Could not update the plan: ${message}` }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult(`Could not update the plan: ${message}`, undefined);
 			}
 		},
 

package/extensions/plan/tools/write.ts

@@ -12,6 +12,7 @@ import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
+import { failedResult, textResult } from "../../../lib/tool-result.ts";
 import { overCap, stepElisionNote } from "../format.ts";
 import { WRITE_PLAN_TOOL, type PlanRuntime } from "../runtime.ts";
 import { MAX_STEPS, PLAN_OUTLINE, planStepSummary } from "../steps.ts";
@@ -39,14 +40,26 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 		name: WRITE_PLAN_TOOL,
 		label: "Write plan",
 		description:
-			"Save the plan you designed as a markdown file under .pi/plans (project root, or the agent directory outside a " +
+			"Save the plan you designed as a markdown file in the plans directory (the agent directory, keyed by " +
 			"repository). Write the complete plan, not a summary, in this outline so it is consistent and scannable:\n\n" +
 			`${PLAN_OUTLINE}\n\n` +
+			"Each section has one job: lead it with its outcome, keep a prose section to a few bullets or two or three " +
+			"sentences, give each step one verifiable outcome with the detail in a nested note, and put the sketch, files, " +
+			"and commands in inline code or a fence rather than pasted prose. " +
+			"When the change alters a surface that already exists, Visual shows it before and after in one fence each; " +
+			"tag a fence only when every line in it is code. " +
+			"The outline is a guide, not a form: drop Context, Approach, Visual, or Risks when there is nothing to say. " +
+			"Keep Steps and Verification — the steps are read from that section (without it, the shallowest list " +
+			"anywhere becomes the steps), and Verification becomes the last todo item. " +
+			"In Steps, each top-level bullet is one outcome in the order you will do them; " +
+			"an indented line continues that outcome, and a deeper bullet is a note. " +
 			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining. " +
 			`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it cannot track.`,
-		promptSnippet: "Save the designed plan as a markdown file under .pi/plans.",
+		promptSnippet: "Save the designed plan as a markdown file in the plans directory.",
 		promptGuidelines: [
 			"While plan mode is active, write the full plan with write_plan, then call exit_plan_mode with the returned path.",
+			"When refining with plan_path, keep every section heading as it was: the review marks changed sections by heading, " +
+				"so a rename reads as an edit.",
 		],
 		parameters: WritePlanParams,
 		defaultActive: false,
@@ -57,27 +70,17 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!runtime.isEnabled()) {
-				return {
-					content: [{ type: "text", text: "Not in plan mode; call enter_plan_mode first." }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult("Not in plan mode; call enter_plan_mode first.", undefined);
 			}
 			const args = params as WritePlanArgs;
 			const summary = planStepSummary(args.content);
 			if (summary.total > MAX_STEPS) {
 				// Refuse before writing: a note after the fact arrives once the file exists and
 				// the review has listed every step, so the overflow is already lost.
-				return {
-					content: [
-						{
-							type: "text",
-							text: `${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
-						},
-					],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult(
+					`${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
+					undefined,
+				);
 			}
 			try {
 				const file = await runtime.plans.write(ctx.cwd, {
@@ -86,22 +89,17 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 					planPath: args.plan_path,
 				});
 				runtime.setLastPlan(ctx, file.path);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
-						},
-					],
-					details: { path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
-				};
+				// A store an older version kept in the checkout was moved in by this
+				// write; say so once, where the user is looking.
+				const moved = runtime.plans.takeNotice();
+				if (moved) ctx.ui.notify(moved, "info");
+				return textResult(
+					`Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
+					{ path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
+				);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return {
-					content: [{ type: "text", text: `Could not write the plan: ${message}` }],
-					details: undefined,
-					isError: true,
-				};
+				return failedResult(`Could not write the plan: ${message}`, undefined);
 			}
 		},
 

package/extensions/plan/tools.ts

@@ -2,9 +2,10 @@
  * Model-facing registration for the plan-mode tools.
  *
  * `enter_plan_mode` lets the model ask to plan before touching code; it needs
- * user confirmation. `write_plan` saves the plan artifact under `.pi/plans` and
- * returns its path. `exit_plan_mode` reads that file back, presents it for
- * approval (a scrollable review screen in the TUI, a select dialog elsewhere),
+ * user confirmation. `write_plan` saves the plan artifact in the plans directory and
+ * returns its path. `cancel_plan_mode` leaves planning without approving, so a
+ * phone user is never trapped in read-only mode. `exit_plan_mode` reads that file
+ * back, presents it for approval (a scrollable review screen in the TUI, a select dialog elsewhere),
  * and on approval seeds the `todo` tool with the plan's steps (through
  * `ctx.executeTool`, so the todo widget and validation run normally).
  * `set_plan_steps` then keeps the plan current: after approval the model ticks
@@ -22,6 +23,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { PlanRuntime } from "./runtime.ts";
+import { registerCancelTool } from "./tools/cancel.ts";
 import { registerEnterTool } from "./tools/enter.ts";
 import { registerExitTool } from "./tools/exit.ts";
 import { registerSetPlanStepsTool } from "./tools/steps.ts";
@@ -34,6 +36,7 @@ export function registerTools(
 	web: PlanWebReview = createPlanWebReview(runtime.plans),
 ): void {
 	registerEnterTool(pi, runtime);
+	registerCancelTool(pi, runtime);
 	registerWriteTool(pi, runtime);
 	registerExitTool(pi, runtime, web);
 	registerSetPlanStepsTool(pi, runtime);