@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/plan/tools/steps.ts

@@ -1,32 +1,34 @@
 /**
- * The `set_plan_steps` tool registration.
+ * The `steps` action of the `plan` tool.
  *
  * It rewrites the plan file's checkboxes in one call, then mirrors the same
  * batch into the todo items approval seeded. A rejected batch leaves both
  * artifacts untouched.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
+import type { AgentToolResult, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { textResult } from "../../../lib/tool-result.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 { callLine, type ToolCallText } from "../../../lib/tui/tool.ts";
 import { describeUpdates, stepLabel } from "../format.ts";
-import { SET_PLAN_STEPS_TOOL, type PlanRuntime } from "../runtime.ts";
+import { PLAN_TOOL, type PlanRuntime } from "../runtime.ts";
 import { extractPlanSteps } from "../steps.ts";
-import type { SetPlanStepsDetails } from "../types.ts";
+import type { PlanDetails, SetPlanStepsDetails } from "../types.ts";
+import { planRefusal } from "./refusal.ts";
 import { mirrorTodos } from "./todo-seed.ts";
 
-const StepUpdateParams = Type.Object({
+/** One step of an `updates` batch, as the tool schema validates it. */
+export const StepUpdateParams = Type.Object({
 	step: Type.Integer({
 		minimum: 1,
 		description: "1-based step number, in the order the plan was approved.",
 	}),
 	status: StringEnum(["pending", "completed"] as const, {
-		description: "The step's new state.",
+		description:
+			"The step's new state: `completed` ticks it, `pending` reopens it. A plan step has no in-progress state.",
 	}),
 	expected: Type.String({
 		description:
@@ -34,90 +36,71 @@ const StepUpdateParams = Type.Object({
 	}),
 });
 
-const SetPlanStepsParams = Type.Object({
-	plan_path: Type.String({
-		description: "Path to the approved plan file, as returned by write_plan or exit_plan_mode.",
-	}),
-	updates: Type.Array(StepUpdateParams, {
-		minItems: 1,
-		description:
-			"The steps to set; each entry sets one step's checkbox, and the last entry wins for a duplicate step. Pass expected as well to refuse a stale step number.",
-	}),
-});
-
-type SetPlanStepsArgs = Static<typeof SetPlanStepsParams>;
-
-export function registerSetPlanStepsTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
-	pi.registerTool({
-		name: SET_PLAN_STEPS_TOOL,
-		label: "Set plan steps",
-		description:
-			"Keep an approved plan file current by setting the checkboxes of the given top-level steps in place. Each step " +
-			"number matches the order the plan was approved in; a step can be marked completed or reopened. Only the " +
-			"checkboxes change; the step text is left as written. The file is rewritten once, and nothing changes when any " +
-			"step is out of range or an entry's expected text no longer matches the file.",
-		promptSnippet: "Tick steps off in the approved plan file.",
-		promptGuidelines: [
-			"After a plan is approved, call set_plan_steps as you complete steps, passing each step's text as expected so a reordered plan is refused instead of mis-ticked.",
-		],
-		parameters: SetPlanStepsParams,
-		executionMode: "sequential",
-		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+/** The fields `action: "steps"` reads. */
+export interface SetPlanStepsArgs {
+	plan_path?: string;
+	updates?: Array<Static<typeof StepUpdateParams>>;
+}
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const args = params as SetPlanStepsArgs;
-			if (runtime.isEnabled()) {
-				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 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 failedResult(`Could not update the plan: ${message}`, undefined);
-			}
-		},
+export async function executeSteps(
+	runtime: PlanRuntime,
+	args: SetPlanStepsArgs,
+	ctx: ExtensionToolContext,
+): Promise<AgentToolResult<PlanDetails>> {
+	if (runtime.isEnabled()) {
+		return planRefusal("steps", "Not while planning; refine the plan with `plan` action `write` instead.");
+	}
+	const planPath = args.plan_path?.trim() ?? "";
+	if (planPath === "") {
+		return planRefusal(
+			"steps",
+			"`steps` needs plan_path: the approved plan file, as `plan` action `exit` returned it.",
+		);
+	}
+	const updates = args.updates ?? [];
+	if (updates.length === 0) {
+		return planRefusal("steps", "`steps` needs updates: the checkbox changes to apply, one entry per step.");
+	}
+	try {
+		const plan = await runtime.plans.setSteps(ctx.cwd, planPath, updates);
+		const steps = extractPlanSteps(plan.content);
+		const done = steps.filter((step) => step.status === "completed").length;
+		const todoNote = await mirrorTodos(ctx, updates);
+		return textResult(
+			`${describeUpdates(updates)} (${done}/${steps.length} done) in ${plan.relativePath}${todoNote}.`,
+			{
+				action: "steps",
+				path: plan.path,
+				relativePath: plan.relativePath,
+				updates,
+				done,
+				total: steps.length,
+			} satisfies SetPlanStepsDetails,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return planRefusal("steps", `Could not update the plan: ${message}`);
+	}
+}
 
-		renderCall(args, theme, context) {
-			const updates = (args as Partial<SetPlanStepsArgs>).updates;
-			const label =
-				updates && updates.length === 1 && updates[0]?.step !== undefined
-					? `step ${updates[0].step}`
-					: updates && updates.length > 1
-						? `${updates.length} steps`
-						: "steps";
-			return callLine(theme, context?.lastComponent, SET_PLAN_STEPS_TOOL, label);
-		},
+export function callSteps(args: SetPlanStepsArgs, theme: Theme, last: unknown): ToolCallText {
+	const updates = args.updates;
+	const label =
+		updates && updates.length === 1 && updates[0]?.step !== undefined
+			? `steps ${updates[0].step}`
+			: updates && updates.length > 1
+				? `steps ${updates.length} steps`
+				: "steps";
+	return callLine(theme, last, PLAN_TOOL, label);
+}
 
-		renderResult(result, options, theme, context) {
-			const text = reuseText(context?.lastComponent);
-			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<SetPlanStepsDetails>(result.details));
-			if ("line" in outcome) {
-				text.setText(outcome.line);
-				return text;
-			}
-			const details = outcome.details;
-			const completed = details.updates.filter((update) => update.status === "completed").map((u) => u.step);
-			const pending = details.updates.filter((update) => update.status === "pending").map((u) => u.step);
-			const heading =
-				completed.length > 0
-					? paint(theme, "ok", `${GLYPHS.check} ${stepLabel(completed)} done`) +
-						(pending.length > 0 ? paint(theme, "meta", ` · ${stepLabel(pending)} reopened`) : "")
-					: paint(theme, "meta", `${stepLabel(pending)} reopened`);
-			text.setText(heading + paint(theme, "faint", ` · ${details.done}/${details.total}`));
-			return text;
-		},
-	});
+export function textSteps(details: SetPlanStepsDetails, theme: Theme): string {
+	const completed = details.updates.filter((update) => update.status === "completed").map((u) => u.step);
+	const pending = details.updates.filter((update) => update.status === "pending").map((u) => u.step);
+	const heading =
+		completed.length > 0
+			? paint(theme, "ok", `${GLYPHS.check} ${stepLabel(completed)} done`) +
+				(pending.length > 0 ? paint(theme, "meta", ` · ${stepLabel(pending)} reopened`) : "")
+			: paint(theme, "meta", `${stepLabel(pending)} reopened`);
+	return heading + paint(theme, "faint", ` · ${details.done}/${details.total}`);
 }

package/extensions/plan/tools/write.ts

@@ -1,135 +1,92 @@
 /**
- * The `write_plan` tool registration.
+ * The `write` action of the `plan` tool.
  *
  * The cap refusal happens before the file is written, so approval never lists a
  * step it cannot track; the store owns naming, containment, and atomicity.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
+import type { AgentToolResult, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../../lib/format.ts";
-import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { textResult } from "../../../lib/tool-result.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 { callLine, type ToolCallText } from "../../../lib/tui/tool.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";
-import type { WritePlanDetails } from "../types.ts";
+import { PLAN_TOOL, type PlanRuntime } from "../runtime.ts";
+import { MAX_STEPS, planStepSummary } from "../steps.ts";
+import type { PlanDetails, WritePlanDetails } from "../types.ts";
+import { planRefusal } from "./refusal.ts";
 
-const WritePlanParams = Type.Object({
-	title: Type.String({
-		description: 'Short title for the plan, used as the file-name slug, e.g. "Add rate limiting".',
-	}),
-	content: Type.String({
-		description: "The complete plan as markdown in the documented outline, including every step.",
-	}),
-	plan_path: Type.Optional(
-		Type.String({
-			description:
-				"Overwrite an existing plan file (one returned by an earlier write_plan) to refine it instead of creating a new file.",
-		}),
-	),
-});
-
-type WritePlanArgs = Static<typeof WritePlanParams>;
-
-export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
-	pi.registerTool({
-		name: WRITE_PLAN_TOOL,
-		label: "Write plan",
-		description:
-			"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 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,
-		executionMode: "sequential",
-		// destructiveHint is true because plan_path overwrites an existing plan
-		// file; a plain write creates a new one.
-		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+/** The fields `action: "write"` reads. */
+export interface WritePlanArgs {
+	title?: string;
+	content?: string;
+	plan_path?: string;
+}
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			if (!runtime.isEnabled()) {
-				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 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, {
-					title: args.title,
-					content: args.content,
-					planPath: args.plan_path,
-				});
-				runtime.setLastPlan(ctx, file.path);
-				// 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");
-				// A refinement says where the text it replaced went: a reviewer's comment that was
-				// carried to a block that moved can be checked against what she actually read.
-				const kept =
-					file.replaced === undefined ? "" : `, keeping the revision it replaced at ${file.replaced.relativePath}`;
-				// A plan that was approved before is now out of step with the todo list, and
-				// the list is only re-seeded by approving it again. Say so here, where the
-				// refinement is made, instead of letting the two disagree in silence.
-				const reseed =
-					runtime.seeded(file.path) === undefined
-						? ""
-						: " This plan was approved before: its todo items are the ones that approval seeded, and approving it again replaces the steps that changed (an item you started or finished is left alone and named).";
-				return textResult(
-					`Wrote the plan to ${file.relativePath}${kept}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}${reseed}`,
-					{ path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
-				);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				return failedResult(`Could not write the plan: ${message}`, undefined);
-			}
-		},
+export async function executeWrite(
+	runtime: PlanRuntime,
+	args: WritePlanArgs,
+	ctx: ExtensionToolContext,
+): Promise<AgentToolResult<PlanDetails>> {
+	if (!runtime.isEnabled()) {
+		return planRefusal("write", "Not in plan mode; call `plan` action `enter` first.");
+	}
+	const title = args.title?.trim() ?? "";
+	if (title === "") {
+		return planRefusal("write", "`write` needs a title: a short name for the plan, used as the file-name slug.");
+	}
+	const content = args.content ?? "";
+	if (content.trim() === "") {
+		return planRefusal("write", "`write` needs content: the complete plan as markdown in the documented outline.");
+	}
+	const summary = planStepSummary(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 planRefusal(
+			"write",
+			`${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call \`plan\` action \`write\` again.`,
+		);
+	}
+	try {
+		const file = await runtime.plans.write(ctx.cwd, { title, content, planPath: args.plan_path });
+		runtime.setLastPlan(ctx, file.path);
+		// 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");
+		// A refinement says where the text it replaced went: a reviewer's comment that was
+		// carried to a block that moved can be checked against what she actually read.
+		const kept =
+			file.replaced === undefined ? "" : `, keeping the revision it replaced at ${file.replaced.relativePath}`;
+		// A plan that was approved before is now out of step with the todo list, and
+		// the list is only re-seeded by approving it again. Say so here, where the
+		// refinement is made, instead of letting the two disagree in silence.
+		const reseed =
+			runtime.seeded(file.path) === undefined
+				? ""
+				: " This plan was approved before: its todo items are the ones that approval seeded, and approving it again replaces the steps that changed (an item you started or finished is left alone and named).";
+		return textResult(
+			`Wrote the plan to ${file.relativePath}${kept}. Call \`plan\` action \`exit\` with plan_path: ${file.path}${stepElisionNote(summary.elided)}${reseed}`,
+			{
+				action: "write",
+				path: file.path,
+				relativePath: file.relativePath,
+				bytes: file.bytes,
+			} satisfies WritePlanDetails,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return planRefusal("write", `Could not write the plan: ${message}`);
+	}
+}
 
-		renderCall(args, theme, context) {
-			const title = (args as Partial<WritePlanArgs>).title;
-			return callLine(theme, context?.lastComponent, WRITE_PLAN_TOOL, title ? sanitizeLine(title) : "plan");
-		},
+export function callWrite(args: WritePlanArgs, theme: Theme, last: unknown): ToolCallText {
+	const title = args.title?.trim() ?? "";
+	return callLine(theme, last, PLAN_TOOL, title === "" ? "write" : `write ${sanitizeLine(title)}`);
+}
 
-		renderResult(result, options, theme, context) {
-			const text = reuseText(context?.lastComponent);
-			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<WritePlanDetails>(result.details));
-			if ("line" in outcome) {
-				text.setText(outcome.line);
-				return text;
-			}
-			text.setText(
-				paint(theme, "ok", `${GLYPHS.check} Saved plan `) + paint(theme, "meta", outcome.details.relativePath),
-			);
-			return text;
-		},
-	});
+export function textWrite(details: WritePlanDetails, theme: Theme): string {
+	return paint(theme, "ok", `${GLYPHS.check} Saved plan `) + paint(theme, "meta", details.relativePath);
 }