pi-goals 0.1.0

package/.pi/extensions/goal/budget.ts

@@ -0,0 +1,74 @@
+import { BUDGET_HARD_STOP_MULTIPLIER, TIME_BUDGET_WARNING_REMAINING_SECONDS, TOKEN_BUDGET_WARNING_REMAINING } from "./constants";
+import type { BudgetLimitReason, BudgetPressure, BudgetPressureKind, GoalState } from "./types";
+
+export function evaluateBudgetPressure(goal: GoalState): BudgetPressure {
+	const token = tokenPressure(goal);
+	const time = timePressure(goal);
+	return moreSevere(token, time);
+}
+
+export function budgetLimitReason(goal: GoalState): BudgetLimitReason | undefined {
+	const pressure = evaluateBudgetPressure(goal);
+	if (pressure.kind === "tokenReached" || pressure.kind === "tokenHardStop") return "tokenBudget";
+	if (pressure.kind === "timeReached" || pressure.kind === "timeHardStop") return "timeBudget";
+	return undefined;
+}
+
+export function isBudgetWarning(kind: BudgetPressureKind): boolean {
+	return kind === "tokenWarning" || kind === "timeWarning";
+}
+
+export function isBudgetReached(kind: BudgetPressureKind): boolean {
+	return kind === "tokenReached" || kind === "timeReached";
+}
+
+export function isBudgetHardStop(kind: BudgetPressureKind): boolean {
+	return kind === "tokenHardStop" || kind === "timeHardStop";
+}
+
+export function isBudgetExhausted(goal: GoalState): BudgetLimitReason | undefined {
+	if (goal.tokenBudget !== undefined && goal.tokensUsed >= goal.tokenBudget) return "tokenBudget";
+	if (goal.timeBudgetSeconds !== undefined && goal.timeUsedSeconds >= goal.timeBudgetSeconds) return "timeBudget";
+	return undefined;
+}
+
+function tokenPressure(goal: GoalState): BudgetPressure {
+	if (goal.tokenBudget === undefined) return none();
+	const remaining = goal.tokenBudget - goal.tokensUsed;
+	if (goal.tokensUsed >= hardStopBudget(goal.tokenBudget)) return pressure("tokenHardStop", remaining);
+	if (goal.tokensUsed >= goal.tokenBudget) return pressure("tokenReached", remaining);
+	if (remaining <= TOKEN_BUDGET_WARNING_REMAINING) return pressure("tokenWarning", remaining);
+	return none();
+}
+
+function timePressure(goal: GoalState): BudgetPressure {
+	if (goal.timeBudgetSeconds === undefined) return none();
+	const remaining = goal.timeBudgetSeconds - goal.timeUsedSeconds;
+	if (goal.timeUsedSeconds >= hardStopBudget(goal.timeBudgetSeconds)) return pressure("timeHardStop", remaining);
+	if (goal.timeUsedSeconds >= goal.timeBudgetSeconds) return pressure("timeReached", remaining);
+	if (remaining <= TIME_BUDGET_WARNING_REMAINING_SECONDS) return pressure("timeWarning", remaining);
+	return none();
+}
+
+function hardStopBudget(budget: number): number {
+	return Math.ceil((budget * Math.round(BUDGET_HARD_STOP_MULTIPLIER * 10)) / 10);
+}
+
+function moreSevere(a: BudgetPressure, b: BudgetPressure): BudgetPressure {
+	return severity(a.kind) >= severity(b.kind) ? a : b;
+}
+
+function severity(kind: BudgetPressureKind): number {
+	if (isBudgetHardStop(kind)) return 3;
+	if (isBudgetReached(kind)) return 2;
+	if (isBudgetWarning(kind)) return 1;
+	return 0;
+}
+
+function pressure(kind: BudgetPressureKind, remaining: number): BudgetPressure {
+	return { kind, remaining };
+}
+
+function none(): BudgetPressure {
+	return { kind: "none" };
+}

package/.pi/extensions/goal/command.ts

@@ -0,0 +1,201 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { GOAL_USAGE, GOAL_USAGE_HINT } from "./constants";
+import { validateObjective } from "./format";
+import { discoverGoalTemplates, resolveGoalTemplateInvocation } from "./templates";
+import { createTelemetry, resetSafetyCounters } from "./telemetry";
+import {
+	createGoalState,
+	getGoal,
+	getTelemetry,
+	persistClearGoal,
+	persistSetGoal,
+	persistTelemetry,
+	persistUpdateGoal,
+} from "./state";
+import { notifyGoal, notifyInfo, notifyWarning, showGoalSummary, showNoGoal, syncGoalUi } from "./ui";
+import type { GoalCommandScheduler, GoalContinuationCanceller, GoalMonitorCanceller, GoalMonitorScheduler, GoalPauseInterrupter, GoalState } from "./types";
+
+type GoalSubcommand = {
+	name: "pause" | "resume" | "clear";
+	description: string;
+};
+
+const GOAL_SUBCOMMANDS: GoalSubcommand[] = [
+	{ name: "pause", description: "Pause the current goal" },
+	{ name: "resume", description: "Resume a paused goal" },
+	{ name: "clear", description: "Clear the current goal" },
+];
+
+export function registerGoalCommand(
+	pi: ExtensionAPI,
+	scheduleContinuation: GoalCommandScheduler,
+	cancelContinuation: GoalContinuationCanceller,
+	interruptActiveTurn: GoalPauseInterrupter,
+	scheduleMonitor: GoalMonitorScheduler,
+	cancelMonitor: GoalMonitorCanceller,
+): void {
+	pi.registerCommand("goal", {
+		description: "Set or view the goal for a long-running task",
+		getArgumentCompletions: goalArgumentCompletions,
+		handler: async (args, ctx) => handleGoalCommand(pi, args, ctx, scheduleContinuation, cancelContinuation, interruptActiveTurn, scheduleMonitor, cancelMonitor),
+	});
+}
+
+export function goalArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const query = argumentPrefix.trimStart();
+	if (/\s/.test(query)) return null;
+	const scored = GOAL_SUBCOMMANDS.map((subcommand) => ({
+		...subcommand,
+		score: subcommandScore(subcommand.name, query),
+	})).filter((item): item is GoalSubcommand & { score: number } => item.score !== undefined);
+	scored.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+	const subcommands = scored.map(({ name, description }) => ({ value: name, label: name, description }));
+	const templates = discoverGoalTemplates()
+		.filter((template) => template.name.toLowerCase().includes(query.toLowerCase()) || template.aliases.some((alias) => alias.toLowerCase().includes(query.toLowerCase())))
+		.slice(0, 20)
+		.map((template) => ({ value: template.name, label: template.name, description: template.description ?? `Goal template from ${template.path}` }));
+	return [...subcommands, ...templates];
+}
+
+function subcommandScore(value: string, query: string): number | undefined {
+	const normalized = query.toLowerCase();
+	if (!normalized) return 0;
+	if (value.startsWith(normalized)) return 1;
+	if (value.includes(normalized)) return 2;
+	return isOrderedMatch(value, normalized) ? 3 : undefined;
+}
+
+function isOrderedMatch(value: string, query: string): boolean {
+	let index = 0;
+	for (const char of query) {
+		index = value.indexOf(char, index);
+		if (index < 0) return false;
+		index++;
+	}
+	return true;
+}
+
+async function handleGoalCommand(
+	pi: ExtensionAPI,
+	args: string,
+	ctx: ExtensionCommandContext,
+	scheduleContinuation: GoalCommandScheduler,
+	cancelContinuation: GoalContinuationCanceller,
+	interruptActiveTurn: GoalPauseInterrupter,
+	scheduleMonitor: GoalMonitorScheduler,
+	cancelMonitor: GoalMonitorCanceller,
+): Promise<void> {
+	const trimmed = args.trim();
+	if (!trimmed) {
+		const goal = getGoal();
+		if (goal) showGoalSummary(ctx, goal);
+		else showNoGoal(ctx);
+		return;
+	}
+
+	const control = GOAL_SUBCOMMANDS.find((subcommand) => subcommand.name === trimmed.toLowerCase())?.name;
+	if (control === "pause") return pauseGoal(pi, ctx, cancelContinuation, interruptActiveTurn, cancelMonitor);
+	if (control === "resume") return resumeGoal(pi, ctx, scheduleContinuation, scheduleMonitor);
+	if (control === "clear") return clearGoal(pi, ctx, cancelContinuation, cancelMonitor);
+
+	await setGoalObjective(pi, resolveTemplateOrObjective(trimmed, ctx), ctx, scheduleContinuation, cancelContinuation, scheduleMonitor, cancelMonitor);
+}
+
+function resolveTemplateOrObjective(input: string, ctx: ExtensionCommandContext): string {
+	const resolution = resolveGoalTemplateInvocation(input);
+	if (resolution.ok) return resolution.template.objective;
+	if ("notTemplate" in resolution) return input;
+	notifyWarning(ctx, resolution.error);
+	return "";
+}
+
+async function setGoalObjective(
+	pi: ExtensionAPI,
+	input: string,
+	ctx: ExtensionCommandContext,
+	scheduleContinuation: GoalCommandScheduler,
+	cancelContinuation: GoalContinuationCanceller,
+	scheduleMonitor: GoalMonitorScheduler,
+	cancelMonitor: GoalMonitorCanceller,
+): Promise<void> {
+	if (!input) return;
+	const validation = validateObjective(input);
+	if (!validation.ok) {
+		notifyWarning(ctx, validation.hint ? `${validation.message}\n${validation.hint}` : validation.message);
+		return;
+	}
+
+	const existing = getGoal();
+	if (existing) {
+		const ok = await ctx.ui.confirm("Replace goal?", `New objective: ${validation.objective}`);
+		if (!ok) {
+			notifyInfo(ctx, "Goal replacement cancelled. Current goal kept.");
+			return;
+		}
+		cancelContinuation(existing.goalId, "replace");
+		cancelMonitor(existing.goalId, "replace");
+	}
+
+	const goal = createGoalState(validation.objective);
+	const telemetry = createTelemetry(goal.goalId, goal.createdAt);
+	persistSetGoal(pi, goal, telemetry, "command");
+	syncGoalUi(ctx, goal);
+	notifyGoal(ctx, goal);
+	scheduleMonitor(ctx);
+	scheduleContinuation(ctx, "created");
+}
+
+function pauseGoal(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	cancelContinuation: GoalContinuationCanceller,
+	interruptActiveTurn: GoalPauseInterrupter,
+	cancelMonitor: GoalMonitorCanceller,
+): void {
+	const goal = getGoal();
+	if (!goal) {
+		notifyInfo(ctx, `${GOAL_USAGE}\nNo goal is currently set.`);
+		return;
+	}
+	cancelContinuation(goal.goalId, "pause");
+	cancelMonitor(goal.goalId, "pause");
+	const paused: GoalState = { ...goal, status: "paused", updatedAt: Date.now() };
+	persistUpdateGoal(pi, paused, getTelemetry(), "command");
+	syncGoalUi(ctx, paused);
+	notifyGoal(ctx, paused);
+	if (!ctx.isIdle()) {
+		interruptActiveTurn(ctx, paused);
+		notifyWarning(ctx, "Goal paused. The active turn was interrupted; run /goal resume to continue.");
+	}
+}
+
+function resumeGoal(pi: ExtensionAPI, ctx: ExtensionCommandContext, scheduleContinuation: GoalCommandScheduler, scheduleMonitor: GoalMonitorScheduler): void {
+	const goal = getGoal();
+	if (!goal) {
+		notifyInfo(ctx, `${GOAL_USAGE}\n${GOAL_USAGE_HINT}`);
+		return;
+	}
+	if (goal.status === "complete") {
+		notifyInfo(ctx, "Goal is complete. Use /goal clear before starting a new goal.");
+		return;
+	}
+	const active: GoalState = { ...goal, status: "active", updatedAt: Date.now() };
+	const telemetry = resetSafetyCounters(getTelemetry());
+	persistUpdateGoal(pi, active, telemetry, "resume");
+	if (telemetry) persistTelemetry(pi, telemetry, "resume");
+	syncGoalUi(ctx, active);
+	notifyGoal(ctx, active);
+	scheduleMonitor(ctx);
+	scheduleContinuation(ctx, "resumed");
+}
+
+function clearGoal(pi: ExtensionAPI, ctx: ExtensionCommandContext, cancelContinuation: GoalContinuationCanceller, cancelMonitor: GoalMonitorCanceller): void {
+	const goal = getGoal();
+	const hadGoal = Boolean(goal);
+	cancelContinuation(goal?.goalId, "clear");
+	cancelMonitor(goal?.goalId, "clear");
+	const result = persistClearGoal(pi, "command");
+	syncGoalUi(ctx, result.goal);
+	notifyInfo(ctx, hadGoal ? "Goal cleared" : "No goal to clear\nThis session does not currently have a goal.");
+}

package/.pi/extensions/goal/constants.ts

@@ -0,0 +1,39 @@
+export const STATE_ENTRY_TYPE = "pi-goal-state";
+export const CONTINUATION_MESSAGE_TYPE = "pi-goal-continuation";
+export const BUDGET_LIMIT_MESSAGE_TYPE = "pi-goal-budget-limit";
+export const PAUSE_MESSAGE_TYPE = "pi-goal-pause";
+export const GOAL_MONITOR_MESSAGE_TYPE = "pi-goal-monitor-steer";
+export const GOAL_MONITOR_LOG_ENTRY_TYPE = "pi-goal-monitor-log";
+
+export const MAX_OBJECTIVE_CHARS = 15000;
+export const LONG_OBJECTIVE_HINT =
+	"Put longer instructions in a file and refer to that file in the goal, for example: /goal follow the instructions in docs/goal.md.";
+
+export const STATUS_UI_KEY = "pi-goal";
+export const WIDGET_UI_KEY = "pi-goal";
+
+export const TELEMETRY_SCHEMA_VERSION = 1 as const;
+export const STATE_EVENT_VERSION = 1 as const;
+
+export const MAX_CONSECUTIVE_AUTO_TURNS = 50;
+export const MAX_NO_PROGRESS_AUTO_TURNS = 3;
+export const OBJECTIVE_EXCERPT_CHARS = 96;
+export const TOKEN_BUDGET_WARNING_REMAINING = 100_000;
+export const TIME_BUDGET_WARNING_REMAINING_SECONDS = 60;
+export const BUDGET_HARD_STOP_MULTIPLIER = 1.1;
+
+export const GOAL_MONITOR_REPORT_INTERVAL_SECONDS = 90;
+export const GOAL_MONITOR_RECENT_LOG_LIMIT = 10;
+export const GOAL_MONITOR_RECENT_BRANCH_ENTRY_LIMIT = 12;
+export const GOAL_MONITOR_ENTRY_SUMMARY_CHARS = 700;
+export const GOAL_MONITOR_PROCESS_TIMEOUT_MS = 60_000;
+export const GOAL_MONITOR_OUTPUT_CHARS = 20_000;
+
+export const CONTINUATION_PROMPT_ID = "pi-goal-continuation-v1";
+export const BUDGET_LIMIT_PROMPT_ID = "pi-goal-budget-limit-v1";
+export const BUDGET_WARNING_PROMPT_ID = "pi-goal-budget-warning-v1";
+export const PAUSE_PROMPT_ID = "pi-goal-pause-v1";
+export const GOAL_MONITOR_PROMPT_ID = "pi-goal-monitor-v1";
+
+export const GOAL_USAGE = "Usage: /goal <objective>";
+export const GOAL_USAGE_HINT = "Example: /goal improve benchmark coverage";

package/.pi/extensions/goal/continuation.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	BUDGET_LIMIT_MESSAGE_TYPE,
+	CONTINUATION_MESSAGE_TYPE,
+	PAUSE_MESSAGE_TYPE,
+	MAX_CONSECUTIVE_AUTO_TURNS,
+	MAX_NO_PROGRESS_AUTO_TURNS,
+} from "./constants";
+import { buildBudgetLimitPrompt, buildContinuationPrompt, buildPausePrompt } from "./prompts";
+import { getGoal, getTelemetry, persistTelemetry } from "./state";
+import { noteBudgetWrapUpSent, noteContinuationScheduled, noteContinuationSkipped, setNextTurnOrigin } from "./telemetry";
+import type { ContinuationReason, GoalState } from "./types";
+
+type PendingContinuation = {
+	goalId: string;
+	reason: ContinuationReason;
+	timer: ReturnType<typeof setTimeout>;
+};
+
+type PendingBudgetWrapUp = {
+	goalId: string;
+	timer: ReturnType<typeof setTimeout>;
+};
+
+let pendingContinuation: PendingContinuation | undefined;
+let budgetWrapUps = new Map<string, PendingBudgetWrapUp>();
+
+export function scheduleMaybeContinueGoal(pi: ExtensionAPI, ctx: ExtensionContext, reason: ContinuationReason): void {
+	const goal = getGoal();
+	if (!goal || goal.status !== "active") return;
+	cancelGoalContinuation(goal.goalId, "reschedule-continuation");
+	const telemetry = noteContinuationScheduled(getTelemetry(), reason);
+	if (telemetry) persistTelemetry(pi, telemetry, "continuation");
+	const goalId = goal.goalId;
+	const timer = setTimeout(() => {
+		if (pendingContinuation?.goalId === goalId) pendingContinuation = undefined;
+		void safelyRun(() => maybeContinueGoal(pi, ctx, reason, goalId));
+	}, 25);
+	pendingContinuation = { goalId, reason, timer };
+}
+
+export function scheduleBudgetLimitWrapUp(pi: ExtensionAPI, ctx: ExtensionContext, goal: GoalState): void {
+	if (budgetWrapUps.has(goal.goalId)) return;
+	const timer = setTimeout(() => {
+		budgetWrapUps.delete(goal.goalId);
+		void safelyRun(() => maybeSendBudgetWrapUp(pi, ctx, goal.goalId));
+	}, 25);
+	budgetWrapUps.set(goal.goalId, { goalId: goal.goalId, timer });
+}
+
+export function cancelGoalContinuation(goalId?: string, _reason = "cancelled"): void {
+	if (pendingContinuation && (!goalId || pendingContinuation.goalId === goalId)) {
+		clearTimeout(pendingContinuation.timer);
+		pendingContinuation = undefined;
+	}
+	for (const [pendingGoalId, pending] of budgetWrapUps) {
+		if (!goalId || pendingGoalId === goalId) {
+			clearTimeout(pending.timer);
+			budgetWrapUps.delete(pendingGoalId);
+		}
+	}
+}
+
+export function interruptActiveGoalTurn(pi: ExtensionAPI, ctx: ExtensionContext, goal: GoalState): void {
+	if (ctx.isIdle()) return;
+	const prompt = buildPausePrompt(goal);
+	pi.sendMessage(
+		{ customType: PAUSE_MESSAGE_TYPE, content: prompt.content, display: false, details: prompt.details },
+		{ deliverAs: "steer" },
+	);
+	ctx.abort();
+}
+
+export function resetContinuationRuntime(): void {
+	cancelGoalContinuation();
+}
+
+async function maybeContinueGoal(pi: ExtensionAPI, ctx: ExtensionContext, reason: ContinuationReason, goalId: string): Promise<void> {
+	const goal = getGoal();
+	if (!goal || goal.goalId !== goalId || goal.status !== "active") return skip(pi, "notActive");
+	if (!ctx.isIdle()) return skip(pi, "notIdle");
+	if (ctx.hasPendingMessages()) return skip(pi, "pendingMessages");
+	const telemetry = getTelemetry();
+	if (telemetry && telemetry.consecutiveAutoTurns >= MAX_CONSECUTIVE_AUTO_TURNS) return skip(pi, "safetyCap");
+	if (telemetry && telemetry.consecutiveNoProgressTurns >= MAX_NO_PROGRESS_AUTO_TURNS) return skip(pi, "safetyCap");
+
+	const prompt = buildContinuationPrompt(goal);
+	setNextTurnOrigin("auto");
+	pi.sendMessage(
+		{ customType: CONTINUATION_MESSAGE_TYPE, content: prompt.content, display: false, details: { ...prompt.details, reason } },
+		{ triggerTurn: true, deliverAs: "followUp" },
+	);
+}
+
+async function maybeSendBudgetWrapUp(pi: ExtensionAPI, ctx: ExtensionContext, goalId: string): Promise<void> {
+	const goal = getGoal();
+	if (!goal || goal.goalId !== goalId || goal.status !== "budgetLimited") return;
+	if (!ctx.isIdle()) return;
+	if (ctx.hasPendingMessages()) return;
+	const prompt = buildBudgetLimitPrompt(goal);
+	setNextTurnOrigin("budgetWrapUp");
+	pi.sendMessage(
+		{ customType: BUDGET_LIMIT_MESSAGE_TYPE, content: prompt.content, display: false, details: prompt.details },
+		{ triggerTurn: true, deliverAs: "followUp" },
+	);
+	const telemetry = noteBudgetWrapUpSent(getTelemetry());
+	if (telemetry) persistTelemetry(pi, telemetry, "budget");
+}
+
+function skip(pi: ExtensionAPI, reason: "notIdle" | "pendingMessages" | "notActive" | "budgetLimited" | "safetyCap"): void {
+	const telemetry = noteContinuationSkipped(getTelemetry(), reason);
+	if (telemetry) persistTelemetry(pi, telemetry, "continuation");
+}
+
+async function safelyRun(task: () => Promise<void>): Promise<void> {
+	try {
+		await task();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!message.includes("ctx is stale")) console.warn(`[pi-goal] continuation failed: ${message}`);
+	}
+}

package/.pi/extensions/goal/format.ts

@@ -0,0 +1,153 @@
+import { budgetLimitReason } from "./budget";
+import { GOAL_USAGE, GOAL_USAGE_HINT, LONG_OBJECTIVE_HINT, MAX_OBJECTIVE_CHARS, OBJECTIVE_EXCERPT_CHARS } from "./constants";
+import type { GoalState, GoalStatus } from "./types";
+
+export type ObjectiveValidation = { ok: true; objective: string } | { ok: false; message: string; hint?: string };
+
+export function validateObjective(input: string): ObjectiveValidation {
+	const objective = input.trim();
+	if (!objective) {
+		return { ok: false, message: "Goal objective must not be empty.", hint: `${GOAL_USAGE}\n${GOAL_USAGE_HINT}` };
+	}
+	if ([...objective].length > MAX_OBJECTIVE_CHARS) {
+		return {
+			ok: false,
+			message: `Goal objective is too long (${[...objective].length}/${MAX_OBJECTIVE_CHARS} characters).`,
+			hint: LONG_OBJECTIVE_HINT,
+		};
+	}
+	return { ok: true, objective };
+}
+
+export function escapeXml(value: string): string {
+	return value
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+export function formatElapsed(seconds: number): string {
+	const total = Math.max(0, Math.floor(seconds));
+	if (total < 60) return `${total}s`;
+	const minutes = Math.floor(total / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const remMinutes = minutes % 60;
+	if (hours < 24) return remMinutes > 0 ? `${hours}h ${remMinutes}m` : `${hours}h`;
+	const days = Math.floor(hours / 24);
+	const remHours = hours % 24;
+	return `${days}d ${remHours}h ${remMinutes}m`;
+}
+
+export function formatTokensCompact(tokens: number): string {
+	const value = Math.max(0, Math.round(tokens));
+	if (value < 1000) return String(value);
+	if (value < 1_000_000) return `${trimFixed(value / 1000)}k`;
+	return `${trimFixed(value / 1_000_000)}M`;
+}
+
+function trimFixed(value: number): string {
+	return value >= 10 ? value.toFixed(0) : value.toFixed(1).replace(/\.0$/, "");
+}
+
+export function statusLabel(status: GoalStatus): string {
+	switch (status) {
+		case "active":
+			return "active";
+		case "paused":
+			return "paused";
+		case "budgetLimited":
+			return "limited by budget";
+		case "complete":
+			return "complete";
+	}
+}
+
+export function goalStatusLabel(goal: GoalState): string {
+	if (goal.status !== "budgetLimited") return statusLabel(goal.status);
+	const reason = budgetLimitReason(goal);
+	if (reason === "tokenBudget") return "token budget reached";
+	if (reason === "timeBudget") return "time budget reached";
+	return "budget reached";
+}
+
+export function commandHint(status: GoalStatus): string {
+	switch (status) {
+		case "active":
+			return "Commands: /goal pause, /goal clear";
+		case "paused":
+			return "Commands: /goal resume, /goal clear";
+		case "budgetLimited":
+		case "complete":
+			return "Commands: /goal clear";
+	}
+}
+
+export function objectiveExcerpt(objective: string, maxChars = OBJECTIVE_EXCERPT_CHARS): string {
+	const chars = [...objective];
+	if (chars.length <= maxChars) return objective;
+	return `${chars.slice(0, Math.max(0, maxChars - 1)).join("")}…`;
+}
+
+export function formatTimeResource(goal: GoalState): string {
+	const used = formatElapsed(goal.timeUsedSeconds);
+	if (goal.timeBudgetSeconds === undefined) return `Time: ${used}`;
+	return `Time: ${used} / ${formatElapsed(goal.timeBudgetSeconds)}`;
+}
+
+export function formatTokenResource(goal: GoalState): string {
+	const used = formatTokensCompact(goal.tokensUsed);
+	if (goal.tokenBudget === undefined) return `Tokens: ${used}`;
+	return `Tokens: ${used} / ${formatTokensCompact(goal.tokenBudget)}`;
+}
+
+export function goalUsageSummary(goal: GoalState): string {
+	return `${formatTimeResource(goal)}; ${formatTokenResource(goal)}`;
+}
+
+export function footerStatusText(goal: GoalState): string {
+	const usage = footerUsage(goal);
+	switch (goal.status) {
+		case "active":
+			return usage ? `Pursuing goal (${usage})` : "Pursuing goal";
+		case "paused":
+			return "Goal paused (/goal resume)";
+		case "budgetLimited":
+			return usage ? `${goalStatusLabel(goal)} (${usage})` : goalStatusLabel(goal);
+		case "complete":
+			return usage ? `Goal achieved (${usage})` : "Goal achieved";
+	}
+}
+
+function footerUsage(goal: GoalState): string | undefined {
+	if (goal.status === "paused") return undefined;
+	if (goal.tokenBudget !== undefined) {
+		const used = formatTokensCompact(goal.tokensUsed);
+		const budget = formatTokensCompact(goal.tokenBudget);
+		if (goal.status === "active") return `${used} / ${budget}`;
+		if (goal.status === "budgetLimited") return `${used} / ${budget} tokens`;
+		return `${used} tokens`;
+	}
+	if (goal.timeBudgetSeconds !== undefined) {
+		const used = formatElapsed(goal.timeUsedSeconds);
+		const budget = formatElapsed(goal.timeBudgetSeconds);
+		return goal.status === "complete" ? used : `${used} / ${budget}`;
+	}
+	return goal.timeUsedSeconds > 0 ? formatElapsed(goal.timeUsedSeconds) : undefined;
+}
+
+export function goalSummaryLines(goal: GoalState): string[] {
+	const lines = [
+		"Goal",
+		`Status: ${goalStatusLabel(goal)}`,
+		`Objective: ${goal.objective}`,
+		`Time used: ${formatElapsed(goal.timeUsedSeconds)}`,
+		`Tokens used: ${formatTokensCompact(goal.tokensUsed)}`,
+	];
+	if (goal.tokenBudget !== undefined) lines.push(`Token budget: ${formatTokensCompact(goal.tokenBudget)}`);
+	if (goal.timeBudgetSeconds !== undefined) lines.push(`Time budget: ${formatElapsed(goal.timeBudgetSeconds)}`);
+	lines.push("", commandHint(goal.status));
+	return lines;
+}

package/.pi/extensions/goal/index.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerGoalCommand } from "./command";
+import { cancelGoalContinuation, interruptActiveGoalTurn, scheduleMaybeContinueGoal } from "./continuation";
+import { registerGoalLifecycle } from "./lifecycle";
+import { cancelGoalMonitor, scheduleGoalMonitor } from "./monitor";
+import { registerGoalTools } from "./tools";
+
+export default function goalExtension(pi: ExtensionAPI): void {
+	registerGoalCommand(
+		pi,
+		(ctx, reason) => scheduleMaybeContinueGoal(pi, ctx, reason),
+		cancelGoalContinuation,
+		(ctx, goal) => interruptActiveGoalTurn(pi, ctx, goal),
+		(ctx) => scheduleGoalMonitor(pi, ctx),
+		cancelGoalMonitor,
+	);
+	registerGoalTools(pi, (ctx, reason) => scheduleMaybeContinueGoal(pi, ctx, reason), cancelGoalContinuation, (ctx) => scheduleGoalMonitor(pi, ctx), cancelGoalMonitor);
+	registerGoalLifecycle(pi);
+}