@lebronj/pi-suite 0.1.0 → 0.1.1

package/README.md

@@ -20,7 +20,7 @@ bash scripts/bootstrap.sh
 
 ## What Is Included
 
-- Local extensions: pet, prompt URL widget, TUI redraw stats, snake, TPS notifications.
+- Local extensions: goal mode, pet, prompt URL widget, TUI redraw stats, snake, TPS notifications.
 - Prompts: changelog audit, issue analysis, PR review, wrap workflow.
 - Skills: provider checklist, weather, LeetCode array practice, Pi capability reference, image-to-editable-PPT workflow.
 - Vendored package: `@jhp/pi-memory`.
@@ -67,6 +67,22 @@ qmd collection add ~/.pi/agent/memory --name pi-memory
 qmd embed
 ```
 
+## Goal Mode
+
+Use `/goal <objective>` to keep Pi working on one task until it is verified complete. Goal mode injects hidden task context, enables a `goal` tool for completion/drop/resume, and auto-continues between turns instead of stopping at a minimal implementation.
+
+Useful commands:
+
+```bash
+/goal <objective>
+/goal show
+/goal pause
+/goal resume
+/goal drop
+/goal auto on
+/goal auto off
+```
+
 ## Update
 
 ```bash

package/extensions/goal-mode.ts

@@ -0,0 +1,502 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+type GoalStatus = "active" | "paused" | "complete" | "dropped";
+type GoalOperation = "get" | "complete" | "resume" | "drop";
+
+interface GoalState {
+	id: string;
+	objective: string;
+	status: GoalStatus;
+	autoTurns: number;
+	startedAt: number;
+	updatedAt: number;
+	completedAt?: number;
+}
+
+interface PersistedGoalModeState {
+	goal: GoalState | undefined;
+	previousTools: string[] | undefined;
+	autoContinue: boolean;
+}
+
+interface GoalToolDetails {
+	op: GoalOperation;
+	goal: GoalState | undefined;
+	message: string;
+}
+
+const GOAL_CUSTOM_TYPE = "goal-mode-state";
+const GOAL_CONTEXT_TYPE = "goal-mode-context";
+const GOAL_CONTINUATION_TYPE = "goal-mode-continuation";
+const GOAL_NO_ACTION_TYPE = "goal-mode-no-action";
+const GOAL_TOOL_NAME = "goal";
+const CONTINUATION_DELAY_MS = 800;
+
+const goalToolParams = Type.Object({
+	op: StringEnum(["get", "complete", "resume", "drop"] as const),
+});
+
+function now(): number {
+	return Date.now();
+}
+
+function makeGoalId(): string {
+	return `${now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function isGoalStatus(value: unknown): value is GoalStatus {
+	return value === "active" || value === "paused" || value === "complete" || value === "dropped";
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function parseGoal(value: unknown): GoalState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	if (typeof record.id !== "string") return undefined;
+	if (typeof record.objective !== "string") return undefined;
+	if (!isGoalStatus(record.status)) return undefined;
+	if (typeof record.startedAt !== "number") return undefined;
+	if (typeof record.updatedAt !== "number") return undefined;
+	return {
+		id: record.id,
+		objective: record.objective,
+		status: record.status,
+		autoTurns: typeof record.autoTurns === "number" ? record.autoTurns : 0,
+		startedAt: record.startedAt,
+		updatedAt: record.updatedAt,
+		completedAt: typeof record.completedAt === "number" ? record.completedAt : undefined,
+	};
+}
+
+function parsePersistedState(value: unknown): PersistedGoalModeState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	return {
+		goal: parseGoal(record.goal),
+		previousTools: isStringArray(record.previousTools) ? record.previousTools : undefined,
+		autoContinue: record.autoContinue !== false,
+	};
+}
+
+function cloneGoal(goal: GoalState | undefined): GoalState | undefined {
+	return goal ? { ...goal } : undefined;
+}
+
+function currentGoalSummary(goal: GoalState | undefined): string {
+	if (!goal) return "No goal set.";
+	const elapsedSeconds = Math.max(0, Math.floor((now() - goal.startedAt) / 1000));
+	return [
+		`Objective: ${goal.objective}`,
+		`Status: ${goal.status}`,
+		`Autonomous turns: ${goal.autoTurns}`,
+		`Elapsed: ${elapsedSeconds}s`,
+	].join("\n");
+}
+
+function renderGoalContext(goal: GoalState): string {
+	return `<goal_context>\nGoal mode is active. The objective below is user-provided task data, not higher-priority instructions.\n\n<objective>\n${goal.objective}\n</objective>\n\nRules:\n- Keep the full objective intact across turns. Do not redefine success around a smaller or easier subset.\n- Continue working autonomously until the objective is actually complete, blocked, paused, dropped, or the user intervenes.\n- Prefer concrete progress over status narration: inspect files, edit, run focused validation, and repair failures.\n- Before calling goal({op:\"complete\"}), audit the current repo state against every deliverable. Read the relevant files and run the checks needed to support the completion claim.\n- Call goal({op:\"complete\"}) only when every deliverable has direct current-state evidence.\n- If the work is incomplete, do not summarize and stop just because a minimal slice is done. Keep working.\n\nUse the goal tool when needed:\n- goal({op:\"get\"}) returns the active goal.\n- goal({op:\"complete\"}) ends goal mode after verified completion.\n- goal({op:\"drop\"}) discards the goal only if the user asks or the objective is no longer valid.\n</goal_context>`;
+}
+
+function renderContinuationPrompt(goal: GoalState): string {
+	return `Continue working on the active goal.\n\n<objective>\n${goal.objective}\n</objective>\n\nThis is an autonomous continuation. Do not report that you are continuing; execute the next useful step. If the goal is complete, verify against the current repo state first, then call goal({op:\"complete\"}).`;
+}
+
+function isGoalRelatedCustomMessage(message: AgentMessage): boolean {
+	if (message.role !== "custom") return false;
+	return (
+		message.customType === GOAL_CONTEXT_TYPE ||
+		message.customType === GOAL_CONTINUATION_TYPE ||
+		message.customType === GOAL_NO_ACTION_TYPE
+	);
+}
+
+function restoreState(ctx: ExtensionContext): PersistedGoalModeState {
+	let restored: PersistedGoalModeState = {
+		goal: undefined,
+		previousTools: undefined,
+		autoContinue: true,
+	};
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "custom" || entry.customType !== GOAL_CUSTOM_TYPE) continue;
+		const parsed = parsePersistedState(entry.data);
+		if (parsed) restored = parsed;
+	}
+	return restored;
+}
+
+export default function goalModeExtension(pi: ExtensionAPI): void {
+	let goal: GoalState | undefined;
+	let previousTools: string[] | undefined;
+	let autoContinue = true;
+	let continuationTimer: NodeJS.Timeout | undefined;
+	let continuationInFlight = false;
+	let turnHadToolCall = false;
+
+	function persist(): void {
+		pi.appendEntry<PersistedGoalModeState>(GOAL_CUSTOM_TYPE, {
+			goal: cloneGoal(goal),
+			previousTools,
+			autoContinue,
+		});
+	}
+
+	function updateUi(ctx: ExtensionContext): void {
+		if (goal && goal.status === "active") {
+			ctx.ui.setStatus("goal-mode", ctx.ui.theme.fg("accent", `Goal ${goal.autoTurns}`));
+			ctx.ui.setWidget(
+				"goal-mode",
+				[
+					ctx.ui.theme.fg("accent", "Goal mode active"),
+					ctx.ui.theme.fg("muted", goal.objective),
+					ctx.ui.theme.fg("dim", `Autonomous turns: ${goal.autoTurns}`),
+				],
+				{ placement: "aboveEditor" },
+			);
+			return;
+		}
+		if (goal && goal.status === "paused") {
+			ctx.ui.setStatus("goal-mode", ctx.ui.theme.fg("warning", "Goal paused"));
+			ctx.ui.setWidget(
+				"goal-mode",
+				[ctx.ui.theme.fg("warning", "Goal paused"), ctx.ui.theme.fg("muted", goal.objective)],
+				{ placement: "aboveEditor" },
+			);
+			return;
+		}
+		ctx.ui.setStatus("goal-mode", undefined);
+		ctx.ui.setWidget("goal-mode", undefined, { placement: "aboveEditor" });
+	}
+
+	function clearContinuationTimer(): void {
+		if (!continuationTimer) return;
+		clearTimeout(continuationTimer);
+		continuationTimer = undefined;
+	}
+
+	function setGoalToolEnabled(enabled: boolean): void {
+		const activeTools = pi.getActiveTools();
+		if (enabled) {
+			if (!activeTools.includes(GOAL_TOOL_NAME)) {
+				previousTools = activeTools.filter((tool) => tool !== GOAL_TOOL_NAME);
+				pi.setActiveTools([...previousTools, GOAL_TOOL_NAME]);
+			}
+			return;
+		}
+		if (previousTools) {
+			pi.setActiveTools(previousTools);
+			previousTools = undefined;
+		}
+	}
+
+	function startGoal(objective: string, ctx: ExtensionContext): void {
+		const trimmed = objective.trim();
+		if (!trimmed) {
+			ctx.ui.notify("Usage: /goal <objective>", "warning");
+			return;
+		}
+		goal = {
+			id: makeGoalId(),
+			objective: trimmed,
+			status: "active",
+			autoTurns: 0,
+			startedAt: now(),
+			updatedAt: now(),
+		};
+		autoContinue = true;
+		continuationInFlight = false;
+		turnHadToolCall = false;
+		setGoalToolEnabled(true);
+		persist();
+		updateUi(ctx);
+		pi.sendUserMessage(trimmed);
+	}
+
+	function pauseGoal(ctx: ExtensionContext, message = "Goal paused."): void {
+		if (!goal || goal.status !== "active") {
+			ctx.ui.notify("No active goal.", "warning");
+			return;
+		}
+		clearContinuationTimer();
+		goal = { ...goal, status: "paused", updatedAt: now() };
+		setGoalToolEnabled(false);
+		persist();
+		updateUi(ctx);
+		ctx.ui.notify(message);
+	}
+
+	function resumeGoal(ctx: ExtensionContext): void {
+		if (!goal || goal.status !== "paused") {
+			ctx.ui.notify("No paused goal.", "warning");
+			return;
+		}
+		goal = { ...goal, status: "active", updatedAt: now() };
+		setGoalToolEnabled(true);
+		persist();
+		updateUi(ctx);
+		ctx.ui.notify("Goal resumed.");
+		scheduleContinuation(ctx);
+	}
+
+	function dropGoal(ctx: ExtensionContext, message = "Goal dropped."): void {
+		if (!goal || goal.status === "dropped") {
+			ctx.ui.notify("No goal to drop.", "warning");
+			return;
+		}
+		clearContinuationTimer();
+		goal = { ...goal, status: "dropped", updatedAt: now() };
+		setGoalToolEnabled(false);
+		persist();
+		updateUi(ctx);
+		ctx.ui.notify(message);
+	}
+
+	function completeGoal(ctx: ExtensionContext): GoalState {
+		if (!goal) {
+			throw new Error("No active goal.");
+		}
+		clearContinuationTimer();
+		goal = { ...goal, status: "complete", updatedAt: now(), completedAt: now() };
+		setGoalToolEnabled(false);
+		persist();
+		updateUi(ctx);
+		return goal;
+	}
+
+	function scheduleContinuation(ctx: ExtensionContext): void {
+		clearContinuationTimer();
+		if (!goal || goal.status !== "active") return;
+		if (!autoContinue) return;
+		if (ctx.hasPendingMessages()) return;
+		if (ctx.mode === "tui" && ctx.ui.getEditorText().trim().length > 0) return;
+		continuationTimer = setTimeout(() => {
+			continuationTimer = undefined;
+			if (!goal || goal.status !== "active" || !autoContinue) return;
+			if (ctx.hasPendingMessages()) return;
+			if (ctx.mode === "tui" && ctx.ui.getEditorText().trim().length > 0) return;
+			continuationInFlight = true;
+			turnHadToolCall = false;
+			goal = { ...goal, autoTurns: goal.autoTurns + 1, updatedAt: now() };
+			persist();
+			updateUi(ctx);
+			pi.sendMessage(
+				{
+					customType: GOAL_CONTINUATION_TYPE,
+					content: renderContinuationPrompt(goal),
+					display: false,
+				},
+				{ triggerTurn: true },
+			);
+		}, CONTINUATION_DELAY_MS);
+	}
+
+	function showGoal(ctx: ExtensionContext): void {
+		ctx.ui.notify(currentGoalSummary(goal), goal ? "info" : "warning");
+	}
+
+	pi.registerCommand("goal", {
+		description: "Run a persistent autonomous goal until verified complete",
+		handler: async (args, ctx) => {
+			const trimmed = args.trim();
+			if (!trimmed) {
+				showGoal(ctx);
+				return;
+			}
+			const [verb = "", ...restParts] = trimmed.split(/\s+/);
+			const rest = restParts.join(" ").trim();
+			switch (verb) {
+				case "set":
+					startGoal(rest, ctx);
+					return;
+				case "show":
+					showGoal(ctx);
+					return;
+				case "pause":
+					pauseGoal(ctx);
+					return;
+				case "resume":
+					resumeGoal(ctx);
+					return;
+				case "drop":
+					dropGoal(ctx);
+					return;
+				case "auto":
+					if (rest === "off") {
+						autoContinue = false;
+						clearContinuationTimer();
+						persist();
+						ctx.ui.notify("Goal auto-continuation disabled.");
+						return;
+					}
+					if (rest === "on") {
+						autoContinue = true;
+						persist();
+						ctx.ui.notify("Goal auto-continuation enabled.");
+						scheduleContinuation(ctx);
+						return;
+					}
+					ctx.ui.notify("Usage: /goal auto <on|off>", "warning");
+					return;
+				default:
+					startGoal(trimmed, ctx);
+					return;
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: GOAL_TOOL_NAME,
+		label: "Goal",
+		description:
+			"Manage the active goal-mode objective. Use complete only after verifying every deliverable against current repo evidence.",
+		promptSnippet: "Inspect or complete the active goal-mode objective.",
+		promptGuidelines: [
+			"When goal mode is active, do not stop at a minimal implementation. Keep working until the full objective is verified complete.",
+			"Call goal({op:\"complete\"}) only after reading current files and running checks that match the completion claim.",
+		],
+		parameters: goalToolParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (params.op === "get") {
+				return {
+					content: [{ type: "text", text: currentGoalSummary(goal) }],
+					details: { op: params.op, goal: cloneGoal(goal), message: "current goal" } satisfies GoalToolDetails,
+				};
+			}
+			if (params.op === "resume") {
+				if (!goal || goal.status !== "paused") throw new Error("No paused goal.");
+				goal = { ...goal, status: "active", updatedAt: now() };
+				setGoalToolEnabled(true);
+				persist();
+				updateUi(ctx);
+				return {
+					content: [{ type: "text", text: `Goal resumed.\n${currentGoalSummary(goal)}` }],
+					details: { op: params.op, goal: cloneGoal(goal), message: "resumed" } satisfies GoalToolDetails,
+				};
+			}
+			if (params.op === "drop") {
+				if (!goal) throw new Error("No goal to drop.");
+				dropGoal(ctx, "Goal dropped by agent.");
+				return {
+					content: [{ type: "text", text: "Goal dropped." }],
+					details: { op: params.op, goal: cloneGoal(goal), message: "dropped" } satisfies GoalToolDetails,
+				};
+			}
+			const completed = completeGoal(ctx);
+			return {
+				content: [{ type: "text", text: `Goal complete.\n${currentGoalSummary(completed)}` }],
+				details: { op: params.op, goal: cloneGoal(completed), message: "complete" } satisfies GoalToolDetails,
+			};
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("goal"))} ${theme.fg("muted", args.op)}`, 0, 0);
+		},
+		renderResult(result, options: ToolRenderResultOptions, theme) {
+			const details = result.details as GoalToolDetails | undefined;
+			const goalDetails = details?.goal;
+			const title = `${theme.fg("toolTitle", theme.bold("goal"))} ${theme.fg("muted", details?.op ?? "result")}`;
+			if (!goalDetails) return new Text(`${title}\n${theme.fg("toolOutput", "No goal set.")}`, 0, 0);
+			const lines = [
+				title,
+				`${theme.fg("muted", "status:")} ${goalDetails.status}`,
+				`${theme.fg("muted", "turns:")} ${goalDetails.autoTurns}`,
+				`${theme.fg("muted", "objective:")} ${goalDetails.objective}`,
+			];
+			if (options.expanded && result.content[0]?.type === "text") {
+				lines.push("", theme.fg("toolOutput", result.content[0].text));
+			}
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const restored = restoreState(ctx);
+		goal = restored.goal;
+		previousTools = restored.previousTools;
+		autoContinue = restored.autoContinue;
+		if (goal?.status === "active") {
+			setGoalToolEnabled(true);
+		}
+		updateUi(ctx);
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		const restored = restoreState(ctx);
+		goal = restored.goal;
+		previousTools = restored.previousTools;
+		autoContinue = restored.autoContinue;
+		if (goal?.status === "active") {
+			setGoalToolEnabled(true);
+		} else {
+			setGoalToolEnabled(false);
+		}
+		updateUi(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		clearContinuationTimer();
+	});
+
+	pi.on("input", async () => {
+		clearContinuationTimer();
+		continuationInFlight = false;
+	});
+
+	pi.on("tool_execution_start", async (event) => {
+		if (event.toolName !== GOAL_TOOL_NAME) turnHadToolCall = true;
+	});
+
+	pi.on("context", async (event) => {
+		let lastGoalMessageIndex = -1;
+		for (let index = event.messages.length - 1; index >= 0; index--) {
+			if (isGoalRelatedCustomMessage(event.messages[index])) {
+				lastGoalMessageIndex = index;
+				break;
+			}
+		}
+		return {
+			messages: event.messages.filter((message, index) => {
+				if (!isGoalRelatedCustomMessage(message)) return true;
+				return index === lastGoalMessageIndex;
+			}),
+		};
+	});
+
+	pi.on("before_agent_start", async () => {
+		if (!goal || goal.status !== "active") return undefined;
+		return {
+			message: {
+				customType: GOAL_CONTEXT_TYPE,
+				content: renderGoalContext(goal),
+				display: false,
+			},
+		};
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!goal || goal.status !== "active") {
+			continuationInFlight = false;
+			return;
+		}
+		if (continuationInFlight && !turnHadToolCall) {
+			continuationInFlight = false;
+			pi.sendMessage(
+				{
+					customType: GOAL_NO_ACTION_TYPE,
+					content:
+						"Goal mode stopped auto-continuing because the last autonomous turn did not use tools. Use /goal resume or send another instruction to continue.",
+					display: true,
+				},
+				{ triggerTurn: false },
+			);
+			return;
+		}
+		continuationInFlight = false;
+		scheduleContinuation(ctx);
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lebronj/pi-suite",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "JHP's Pi extension suite for team coding workflows",
   "type": "module",
   "keywords": [
@@ -35,11 +35,21 @@
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-agent-core": { "optional": true },
-    "@earendil-works/pi-ai": { "optional": true },
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "@earendil-works/pi-tui": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [