pi-goals 0.1.0

package/.pi/extensions/goal/types.ts

@@ -0,0 +1,168 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
+
+export type GoalState = {
+	goalId: string;
+	objective: string;
+	status: GoalStatus;
+	tokenBudget?: number;
+	timeBudgetSeconds?: number;
+	tokensUsed: number;
+	timeUsedSeconds: number;
+	createdAt: number;
+	updatedAt: number;
+};
+
+export type TurnOrigin = "user" | "auto" | "budgetWrapUp";
+export type ContinuationReason = "created" | "resumed" | "agentEnd";
+export type ContinuationSkipReason = "notIdle" | "pendingMessages" | "notActive" | "budgetLimited" | "safetyCap";
+export type SafetyPauseReason = "maxAutoTurns" | "noProgress" | "abort";
+export type BudgetLimitReason = "tokenBudget" | "timeBudget";
+export type BudgetWarningReason = "tokenWarning" | "timeWarning";
+export type BudgetHardStopReason = "tokenHardStop" | "timeHardStop";
+export type BudgetPressureKind = "none" | BudgetWarningReason | "tokenReached" | "timeReached" | BudgetHardStopReason;
+export type BudgetPressure = { kind: BudgetPressureKind; remaining?: number };
+
+export type GoalTelemetrySnapshot = {
+	version: 1;
+	goalId: string;
+	totalTurns: number;
+	userTurns: number;
+	autoTurns: number;
+	consecutiveAutoTurns: number;
+	consecutiveNoProgressTurns: number;
+	lastTurnOrigin?: TurnOrigin;
+	lastContinuationReason?: ContinuationReason;
+	lastSkipReason?: ContinuationSkipReason;
+	lastTurnToolCallCount?: number;
+	lastTurnToolResultCount?: number;
+	lastTurnCompletedGoal?: boolean;
+	budgetWrapUpSent?: boolean;
+	lastProgressAt?: number;
+	lastSafetyPauseReason?: SafetyPauseReason;
+	lastBudgetLimitReason?: BudgetLimitReason;
+	lastBudgetWarningReason?: BudgetWarningReason;
+	lastBudgetHardStopReason?: BudgetHardStopReason;
+	tokenBudgetWarningSent?: boolean;
+	timeBudgetWarningSent?: boolean;
+	updatedAt: number;
+};
+
+export type PiGoalEventKind = "set" | "update" | "account" | "telemetry" | "clear";
+export type PiGoalEventReason =
+	| "command"
+	| "tool"
+	| "turn"
+	| "budget"
+	| "abort"
+	| "resume"
+	| "reload"
+	| "continuation"
+	| "safety";
+
+export type PiGoalStateEvent = {
+	version: 1;
+	kind: PiGoalEventKind;
+	goalId?: string;
+	goal: GoalState | null;
+	telemetry?: GoalTelemetrySnapshot | null;
+	delta?: { timeUsedSeconds?: number; tokensUsed?: number };
+	reason: PiGoalEventReason;
+	at: number;
+};
+
+export type GoalRuntimeState = {
+	goal: GoalState | null;
+	telemetry: GoalTelemetrySnapshot | null;
+};
+
+export type TurnAccountingSnapshot = {
+	goalId: string;
+	startedAt: number;
+	origin: TurnOrigin;
+	toolCallCount: number;
+	toolResultCount: number;
+	progressCount: number;
+	completedGoal: boolean;
+};
+
+export type GoalSteeringKind = "continuation" | "budgetLimit" | "pause" | "monitorSteer";
+
+export type GoalSteeringDetails = {
+	goalId: string;
+	kind: GoalSteeringKind;
+	promptId: string;
+	createdAt: number;
+	reason?: ContinuationReason | "budget" | "pause";
+};
+
+export type StreamBudgetSignal = "hardStop" | "reached" | "warning";
+
+export type GoalCommandScheduler = (ctx: ExtensionContext, reason: ContinuationReason) => void;
+export type GoalContinuationCanceller = (goalId?: string, reason?: string) => void;
+export type GoalPauseInterrupter = (ctx: ExtensionContext, goal: GoalState) => void;
+export type GoalMonitorScheduler = (ctx: ExtensionContext) => void;
+export type GoalMonitorCanceller = (goalId?: string, reason?: string) => void;
+
+export type GoalMonitorAction = "watch" | "steer" | "escalate";
+export type GoalMonitorConfidence = "low" | "medium" | "high";
+
+export type GoalMonitorDecision = {
+	action: GoalMonitorAction;
+	confidence: GoalMonitorConfidence;
+	pattern?: string;
+	evidence: string[];
+	steer?: string;
+	logNote: string;
+	parseWarnings?: string[];
+};
+
+export type GoalMonitorLogEntry = {
+	version: 1;
+	goalId: string;
+	reportId: string;
+	decisionId: string;
+	at: number;
+	action: GoalMonitorAction;
+	confidence: GoalMonitorConfidence;
+	pattern?: string;
+	evidenceSummary: string;
+	steerInjected: boolean;
+	logNote: string;
+};
+
+export type GoalMonitorRecentEntry = {
+	index: number;
+	type: string;
+	role?: string;
+	timestamp?: string | number;
+	toolName?: string;
+	isError?: boolean;
+	summary: string;
+};
+
+export type GoalMonitorReport = {
+	version: 1;
+	reportId: string;
+	goalId: string;
+	sentAt: number;
+	elapsedSinceGoalStartSeconds: number;
+	elapsedSincePreviousReportSeconds?: number;
+	goal: GoalState;
+	telemetry: GoalTelemetrySnapshot | null;
+	session: {
+		cwd: string;
+		sessionId?: string;
+		branchEntryCount: number;
+	};
+	recentEntries: GoalMonitorRecentEntry[];
+	recentLogEntries: GoalMonitorLogEntry[];
+};
+
+export type MutationResult = {
+	ok: boolean;
+	goal: GoalState | null;
+	telemetry: GoalTelemetrySnapshot | null;
+	message?: string;
+};

package/.pi/extensions/goal/ui.ts

@@ -0,0 +1,41 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { GOAL_USAGE, GOAL_USAGE_HINT, STATUS_UI_KEY, WIDGET_UI_KEY } from "./constants";
+import { footerStatusText, goalSummaryLines, goalUsageSummary, statusLabel } from "./format";
+import type { GoalState } from "./types";
+import { goalWidgetFactory } from "./widget";
+
+export function syncGoalUi(ctx: ExtensionContext, goal: GoalState | null): void {
+	if (!goal) {
+		ctx.ui.setStatus(STATUS_UI_KEY, undefined);
+		ctx.ui.setWidget(WIDGET_UI_KEY, undefined);
+		return;
+	}
+	ctx.ui.setStatus(STATUS_UI_KEY, footerStatusText(goal));
+	ctx.ui.setWidget(WIDGET_UI_KEY, goalWidgetFactory(goal), { placement: "aboveEditor" });
+}
+
+export function showNoGoal(ctx: ExtensionContext): void {
+	ctx.ui.notify(`${GOAL_USAGE}\n${GOAL_USAGE_HINT}`, "info");
+}
+
+export function showGoalSummary(ctx: ExtensionContext, goal: GoalState): void {
+	ctx.ui.notify(goalSummaryLines(goal).join("\n"), "info");
+}
+
+export function notifyGoal(ctx: ExtensionContext, goal: GoalState, prefix = "Goal"): void {
+	ctx.ui.notify(`${prefix} ${statusLabel(goal.status)}\n${goalUsageSummary(goal)}`, "info");
+}
+
+export function notifyInfo(ctx: ExtensionContext, message: string): void {
+	ctx.ui.notify(message, "info");
+}
+
+export function notifyWarning(ctx: ExtensionContext, message: string): void {
+	ctx.ui.notify(message, "warning");
+}
+
+export async function promptResumePausedGoal(ctx: ExtensionContext, goal: GoalState): Promise<boolean> {
+	const choice = await ctx.ui.select("Resume paused goal?", ["Resume goal", "Leave paused"]);
+	return choice === "Resume goal";
+}
+

package/.pi/extensions/goal/widget.ts

@@ -0,0 +1,159 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { commandHint, formatElapsed, formatTokensCompact, goalStatusLabel, objectiveExcerpt } from "./format";
+import type { GoalState, GoalStatus } from "./types";
+
+type ThemeColor = "accent" | "success" | "warning" | "error" | "muted" | "dim" | "text" | "border" | "borderAccent";
+
+type GoalWidgetTheme = {
+	fg(color: ThemeColor, text: string): string;
+	bold(text: string): string;
+};
+
+type GoalWidgetComponent = {
+	render(width: number): string[];
+	invalidate(): void;
+};
+
+type StatusStyle = {
+	icon: string;
+	label: string;
+	color: ThemeColor;
+};
+
+type ResourceSpec = {
+	icon: string;
+	label: string;
+	used: number;
+	budget?: number;
+	format(value: number): string;
+	suffix?: string;
+};
+
+const BAR_WIDTH = 10;
+const MIN_CARD_WIDTH = 28;
+const MAX_CARD_WIDTH = 72;
+
+export function goalWidgetFactory(goal: GoalState): (_tui: unknown, theme: GoalWidgetTheme) => GoalWidgetComponent {
+	return (_tui, theme) => new GoalWidget(goal, theme);
+}
+
+export function renderGoalWidget(goal: GoalState, theme: GoalWidgetTheme, width: number): string[] {
+	if (width < MIN_CARD_WIDTH) return compactLines(goal, theme, width);
+	const cardWidth = Math.min(MAX_CARD_WIDTH, Math.max(MIN_CARD_WIDTH, width));
+	const contentWidth = cardWidth - 4;
+	const style = statusStyle(goal);
+	const lines = [
+		topBorder(cardWidth, style, theme),
+		contentLine(theme.fg("dim", objectiveExcerpt(goal.objective, contentWidth)), contentWidth, theme),
+		contentLine(resourceLine(timeResource(goal), theme), contentWidth, theme),
+		contentLine(resourceLine(tokenResource(goal), theme), contentWidth, theme),
+		contentLine(commandLine(goal.status, theme), contentWidth, theme),
+		bottomBorder(cardWidth, theme),
+	];
+	return lines.map((line) => truncateToWidth(line, cardWidth));
+}
+
+class GoalWidget implements GoalWidgetComponent {
+	constructor(private readonly goal: GoalState, private readonly theme: GoalWidgetTheme) {}
+
+	render(width: number): string[] {
+		return renderGoalWidget(this.goal, this.theme, width);
+	}
+
+	invalidate(): void {}
+}
+
+function compactLines(goal: GoalState, theme: GoalWidgetTheme, width: number): string[] {
+	const style = statusStyle(goal);
+	const status = theme.fg(style.color, `${style.icon} ${style.label}`);
+	return [
+		truncateToWidth(`${status} ${objectiveExcerpt(goal.objective, Math.max(6, width - 10))}`, width),
+		truncateToWidth(`${timeValue(goal)}  ${tokenValue(goal)}`, width),
+		truncateToWidth(commandHint(goal.status).replace(/^Commands: /, ""), width),
+	];
+}
+
+function topBorder(width: number, style: StatusStyle, theme: GoalWidgetTheme): string {
+	const title = theme.bold(theme.fg(style.color, `${style.icon} pi-goal`));
+	const badge = theme.fg(style.color, style.label);
+	const left = `╭─ ${title} `;
+	const right = ` ${badge} ─╮`;
+	const fill = "─".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+	return `${left}${theme.fg("border", fill)}${right}`;
+}
+
+function bottomBorder(width: number, theme: GoalWidgetTheme): string {
+	return theme.fg("border", `╰${"─".repeat(Math.max(0, width - 2))}╯`);
+}
+
+function contentLine(content: string, width: number, theme: GoalWidgetTheme): string {
+	const clipped = padAnsi(truncateToWidth(content, width, "…"), width);
+	return `${theme.fg("border", "│")} ${clipped} ${theme.fg("border", "│")}`;
+}
+
+function commandLine(status: GoalStatus, theme: GoalWidgetTheme): string {
+	const commands = commandHint(status).replace(/^Commands: /, "").split(", ");
+	return `${theme.fg("muted", "next")} ${commands.map((cmd) => theme.fg("accent", cmd)).join("  ")}`;
+}
+
+function resourceLine(spec: ResourceSpec, theme: GoalWidgetTheme): string {
+	if (spec.budget === undefined) return `${spec.icon} ${theme.fg("muted", spec.label)}  ${resourceValue(spec.used, spec.format, spec.suffix)}`;
+	const percent = percentage(spec.used, spec.budget);
+	return [
+		`${spec.icon} ${theme.fg("muted", spec.label.padEnd(6))}`,
+		progressBar(percent, theme),
+		`${spec.format(spec.used)} / ${spec.format(spec.budget)}`,
+		`${percent}%`,
+	].join("  ");
+}
+
+function progressBar(percent: number, theme: GoalWidgetTheme): string {
+	const filled = Math.round((clamp(percent, 0, 100) / 100) * BAR_WIDTH);
+	return `${theme.fg("success", "█".repeat(filled))}${theme.fg("dim", "░".repeat(BAR_WIDTH - filled))}`;
+}
+
+function timeResource(goal: GoalState): ResourceSpec {
+	return { icon: "⏱", label: "Time", used: goal.timeUsedSeconds, budget: goal.timeBudgetSeconds, format: formatElapsed };
+}
+
+function tokenResource(goal: GoalState): ResourceSpec {
+	return { icon: "◈", label: "Tokens", used: goal.tokensUsed, budget: goal.tokenBudget, format: formatTokensCompact, suffix: "tokens" };
+}
+
+function timeValue(goal: GoalState): string {
+	return goal.timeBudgetSeconds === undefined ? `⏱ ${formatElapsed(goal.timeUsedSeconds)}` : `⏱ ${formatElapsed(goal.timeUsedSeconds)} / ${formatElapsed(goal.timeBudgetSeconds)}`;
+}
+
+function tokenValue(goal: GoalState): string {
+	return goal.tokenBudget === undefined ? `◈ ${formatTokensCompact(goal.tokensUsed)} tokens` : `◈ ${formatTokensCompact(goal.tokensUsed)} / ${formatTokensCompact(goal.tokenBudget)}`;
+}
+
+function resourceValue(value: number, format: (value: number) => string, suffix?: string): string {
+	const formatted = format(value);
+	return suffix ? `${formatted} ${suffix}` : formatted;
+}
+
+function percentage(used: number, budget: number): number {
+	return clamp(Math.round((Math.max(0, used) / Math.max(1, budget)) * 100), 0, 100);
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value));
+}
+
+function padAnsi(text: string, width: number): string {
+	return `${text}${" ".repeat(Math.max(0, width - visibleWidth(text)))}`;
+}
+
+function statusStyle(goal: GoalState): StatusStyle {
+	switch (goal.status) {
+		case "active":
+			return { icon: "🎯", label: "active", color: "accent" };
+		case "paused":
+			return { icon: "⏸", label: "paused", color: "warning" };
+		case "budgetLimited":
+			return { icon: "⚠", label: goalStatusLabel(goal), color: "warning" };
+		case "complete":
+			return { icon: "✓", label: "complete", color: "success" };
+	}
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# pi-goals
+
+Persistent goal tracking for [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), inspired by Codex CLI's `/goal` workflow.
+
+> Early preview: this package is being prepared for open-source release. APIs and install ergonomics may change before `1.0.0`.
+
+## What it provides
+
+- `/goal` command for creating, pausing, resuming, replacing, and clearing a persistent objective.
+- Goal state persisted into the Pi session branch.
+- Goal-aware runtime continuation and monitoring hooks.
+- Model tools for inspecting and updating the active goal.
+- Compact Pi UI status/widget integration.
+
+## Install
+
+```bash
+npm install pi-goals
+```
+
+## Use with Pi
+
+The extension entrypoint is published as TypeScript source at:
+
+```text
+.pi/extensions/goal/index.ts
+```
+
+Until a packaged loader is finalized, copy or reference the extension directory from `node_modules/pi-goals/.pi/extensions/goal` in your Pi setup.
+
+For local validation:
+
+```bash
+npm run quality:goal
+```
+
+## Status
+
+This is an early release intended to claim the public package name and make the current implementation available for collaborators and early testers.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-goals",
+  "version": "0.1.0",
+  "description": "Persistent goal tracking extension for Pi, inspired by Codex CLI /goal.",
+  "main": ".pi/extensions/goal/index.ts",
+  "files": [
+    ".pi/extensions/goal/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck:goal": "tsc --noEmit --target ES2022 --module ESNext --moduleResolution node --ignoreDeprecations 6.0 --types node --strict --skipLibCheck .pi/extensions/goal/*.ts",
+    "slop:goal": "if rg -n 'as unknown as|as any' .pi/extensions/goal; then exit 1; else exit 0; fi",
+    "quality:goal": "sentrux gate .pi/extensions/goal && sentrux check .pi/extensions/goal && npm run slop:goal && npm run typecheck:goal && pi --offline --no-session --no-tools -e .pi/extensions/goal/index.ts --list-models >/tmp/pi-goal-quality-load.txt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transcendr/pi-goals.git"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "agent",
+    "goal",
+    "coding-agent"
+  ],
+  "author": "Bryan Price-McConnahea (@slopwareindy // withbryan.work)",
+  "license": "MIT",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/transcendr/pi-goals/issues"
+  },
+  "homepage": "https://github.com/transcendr/pi-goals#readme",
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@types/node": "^25.6.2",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.3"
+  }
+}