pi-goals 0.1.0

package/.pi/extensions/goal/telemetry.ts

@@ -0,0 +1,153 @@
+import { TELEMETRY_SCHEMA_VERSION } from "./constants";
+import type {
+	BudgetHardStopReason,
+	BudgetLimitReason,
+	BudgetWarningReason,
+	ContinuationReason,
+	ContinuationSkipReason,
+	GoalTelemetrySnapshot,
+	SafetyPauseReason,
+	TurnAccountingSnapshot,
+	TurnOrigin,
+} from "./types";
+
+let nextTurnOrigin: TurnOrigin = "user";
+
+export function setNextTurnOrigin(origin: TurnOrigin): void {
+	nextTurnOrigin = origin;
+}
+
+export function consumeNextTurnOrigin(): TurnOrigin {
+	const origin = nextTurnOrigin;
+	nextTurnOrigin = "user";
+	return origin;
+}
+
+export function createTelemetry(goalId: string, now = Date.now()): GoalTelemetrySnapshot {
+	return {
+		version: TELEMETRY_SCHEMA_VERSION,
+		goalId,
+		totalTurns: 0,
+		userTurns: 0,
+		autoTurns: 0,
+		consecutiveAutoTurns: 0,
+		consecutiveNoProgressTurns: 0,
+		updatedAt: now,
+	};
+}
+
+export function isTelemetry(value: unknown): value is GoalTelemetrySnapshot {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value as Record<string, unknown>;
+	return v.version === TELEMETRY_SCHEMA_VERSION && typeof v.goalId === "string";
+}
+
+export function noteContinuationScheduled(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: ContinuationReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, lastContinuationReason: reason, lastSkipReason: undefined, updatedAt: now };
+}
+
+export function noteContinuationSkipped(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: ContinuationSkipReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, lastSkipReason: reason, updatedAt: now };
+}
+
+export function noteBudgetWrapUpSent(
+	telemetry: GoalTelemetrySnapshot | null,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, budgetWrapUpSent: true, updatedAt: now };
+}
+
+export function noteBudgetLimit(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: BudgetLimitReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, lastBudgetLimitReason: reason, updatedAt: now };
+}
+
+export function noteBudgetWarning(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: BudgetWarningReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return {
+		...telemetry,
+		lastBudgetWarningReason: reason,
+		tokenBudgetWarningSent: telemetry.tokenBudgetWarningSent || reason === "tokenWarning",
+		timeBudgetWarningSent: telemetry.timeBudgetWarningSent || reason === "timeWarning",
+		updatedAt: now,
+	};
+}
+
+export function noteBudgetHardStop(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: BudgetHardStopReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, lastBudgetHardStopReason: reason, updatedAt: now };
+}
+
+export function noteSafetyPause(
+	telemetry: GoalTelemetrySnapshot | null,
+	reason: SafetyPauseReason,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return { ...telemetry, lastSafetyPauseReason: reason, updatedAt: now };
+}
+
+export function resetSafetyCounters(
+	telemetry: GoalTelemetrySnapshot | null,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry) return null;
+	return {
+		...telemetry,
+		consecutiveAutoTurns: 0,
+		consecutiveNoProgressTurns: 0,
+		lastSafetyPauseReason: undefined,
+		updatedAt: now,
+	};
+}
+
+export function applyTurnTelemetry(
+	telemetry: GoalTelemetrySnapshot | null,
+	turn: TurnAccountingSnapshot,
+	madeProgress: boolean,
+	now = Date.now(),
+): GoalTelemetrySnapshot | null {
+	if (!telemetry || telemetry.goalId !== turn.goalId) return telemetry;
+	const auto = turn.origin === "auto" || turn.origin === "budgetWrapUp";
+	return {
+		...telemetry,
+		totalTurns: telemetry.totalTurns + 1,
+		userTurns: telemetry.userTurns + (turn.origin === "user" ? 1 : 0),
+		autoTurns: telemetry.autoTurns + (auto ? 1 : 0),
+		consecutiveAutoTurns: auto ? telemetry.consecutiveAutoTurns + 1 : 0,
+		consecutiveNoProgressTurns: auto && !madeProgress ? telemetry.consecutiveNoProgressTurns + 1 : 0,
+		lastTurnOrigin: turn.origin,
+		lastTurnToolCallCount: turn.toolCallCount,
+		lastTurnToolResultCount: turn.toolResultCount,
+		lastTurnCompletedGoal: turn.completedGoal,
+		lastProgressAt: madeProgress ? now : telemetry.lastProgressAt,
+		updatedAt: now,
+	};
+}
+
+export function makeTurnSnapshot(goalId: string, origin: TurnOrigin, startedAt = Date.now()): TurnAccountingSnapshot {
+	return { goalId, origin, startedAt, toolCallCount: 0, toolResultCount: 0, progressCount: 0, completedGoal: false };
+}

package/.pi/extensions/goal/templates.ts

@@ -0,0 +1,228 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative, sep } from "node:path";
+
+const TEMPLATE_DIR = ".pi-goals";
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_COMMAND_OUTPUT_LIMIT = 20_000;
+const SKIP_DIRS = new Set([".git", "node_modules", "references", "dist", "build", ".next", ".cache"]);
+
+export type GoalTemplate = {
+	name: string;
+	path: string;
+	description?: string;
+	aliases: string[];
+	allowCommands: boolean;
+	commandTimeoutMs: number;
+	commandOutputLimit: number;
+	body: string;
+};
+
+export type ResolvedGoalTemplate = {
+	name: string;
+	path: string;
+	objective: string;
+};
+
+export type TemplateResolution = { ok: true; template: ResolvedGoalTemplate } | { ok: false; error: string } | { ok: false; notTemplate: true };
+
+type ParsedInvocation = {
+	name: string;
+	flags: Record<string, string>;
+	args: string;
+};
+
+type Frontmatter = Record<string, string>;
+
+export function discoverGoalTemplates(root = process.cwd()): GoalTemplate[] {
+	const templates: GoalTemplate[] = [];
+	for (const dir of findTemplateDirs(root)) collectTemplates(root, dir, templates);
+	templates.sort((a, b) => a.name.localeCompare(b.name));
+	return templates;
+}
+
+export function resolveGoalTemplateInvocation(input: string, root = process.cwd()): TemplateResolution {
+	const parsed = parseInvocation(input);
+	if (!parsed) return { ok: false, notTemplate: true };
+	const template = findTemplate(parsed.name, root);
+	if (!template) return { ok: false, notTemplate: true };
+	try {
+		const values = { ...parsed.flags, args: parsed.args };
+		const interpolated = interpolate(template.body, values);
+		const objective = resolveInlineCommands(interpolated, template, root).trim();
+		return { ok: true, template: { name: template.name, path: template.path, objective } };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function findTemplate(nameOrAlias: string, root: string): GoalTemplate | undefined {
+	return discoverGoalTemplates(root).find((template) => template.name === nameOrAlias || template.aliases.includes(nameOrAlias));
+}
+
+function findTemplateDirs(root: string): string[] {
+	const dirs: string[] = [];
+	walk(root, (path) => {
+		if (basename(path) === TEMPLATE_DIR) dirs.push(path);
+	});
+	return dirs;
+}
+
+function walk(dir: string, visit: (path: string) => void): void {
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (SKIP_DIRS.has(entry)) continue;
+		const path = join(dir, entry);
+		let stats;
+		try {
+			stats = statSync(path);
+		} catch {
+			continue;
+		}
+		if (!stats.isDirectory()) continue;
+		visit(path);
+		if (entry !== TEMPLATE_DIR) walk(path, visit);
+	}
+}
+
+function collectTemplates(root: string, templateDir: string, templates: GoalTemplate[]): void {
+	collectMarkdown(templateDir, (path) => {
+		const raw = readFileSync(path, "utf8");
+		const parsed = parseFrontmatter(raw);
+		const relativeName = stripMarkdownExt(relative(templateDir, path).split(sep).join("/"));
+		templates.push({
+			name: relativeName,
+			path: relative(root, path),
+			description: parsed.frontmatter.description || firstContentLine(parsed.body),
+			aliases: parseList(parsed.frontmatter.aliases),
+			allowCommands: parseBoolean(parsed.frontmatter.allow_commands),
+			commandTimeoutMs: parsePositiveInt(parsed.frontmatter.command_timeout_ms, DEFAULT_COMMAND_TIMEOUT_MS),
+			commandOutputLimit: parsePositiveInt(parsed.frontmatter.command_output_limit, DEFAULT_COMMAND_OUTPUT_LIMIT),
+			body: parsed.body,
+		});
+	});
+}
+
+function collectMarkdown(dir: string, visit: (path: string) => void): void {
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const path = join(dir, entry);
+		const stats = statSync(path);
+		if (stats.isDirectory()) collectMarkdown(path, visit);
+		else if ([".md", ".markdown", ".txt"].includes(extname(entry))) visit(path);
+	}
+}
+
+function parseFrontmatter(raw: string): { frontmatter: Frontmatter; body: string } {
+	if (!raw.startsWith("---\n")) return { frontmatter: {}, body: raw };
+	const end = raw.indexOf("\n---", 4);
+	if (end < 0) return { frontmatter: {}, body: raw };
+	const frontmatter: Frontmatter = {};
+	for (const line of raw.slice(4, end).split(/\r?\n/)) {
+		const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+		if (match) frontmatter[match[1]] = stripQuotes(match[2].trim());
+	}
+	return { frontmatter, body: raw.slice(end + 4).replace(/^\r?\n/, "") };
+}
+
+function parseInvocation(input: string): ParsedInvocation | undefined {
+	const trimmed = input.trim();
+	if (!trimmed) return undefined;
+	const match = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+	if (!match) return undefined;
+	const name = match[1];
+	let rest = match[2] ?? "";
+	let args = "";
+	const delimiter = rest.indexOf(" -- ");
+	if (delimiter >= 0) {
+		args = rest.slice(delimiter + 4).trim();
+		rest = rest.slice(0, delimiter).trim();
+	}
+	return { name, flags: parseFlags(rest), args };
+}
+
+function parseFlags(input: string): Record<string, string> {
+	const values: Record<string, string> = {};
+	const tokens = input.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+	for (let i = 0; i < tokens.length; i++) {
+		const token = unquote(tokens[i]);
+		if (!token.startsWith("--")) continue;
+		const eq = token.indexOf("=");
+		if (eq > 2) {
+			values[token.slice(2, eq)] = token.slice(eq + 1);
+			continue;
+		}
+		const next = tokens[i + 1] && !tokens[i + 1].startsWith("--") ? unquote(tokens[++i]) : "true";
+		values[token.slice(2)] = next;
+	}
+	return values;
+}
+
+function interpolate(text: string, values: Record<string, string>): string {
+	return text.replace(/\{\{\s*([A-Za-z0-9_-]+)\s*\}\}/g, (_match, key: string) => {
+		if (values[key] === undefined) throw new Error(`Missing template value for {{${key}}}.`);
+		return values[key];
+	});
+}
+
+function resolveInlineCommands(text: string, template: GoalTemplate, cwd: string): string {
+	return text.replace(/!`([^`]+)`/g, (_match, command: string) => {
+		if (!template.allowCommands) throw new Error(`Template ${template.name} uses inline commands but allow_commands is not true.`);
+		return runCommand(command, template, cwd);
+	});
+}
+
+function runCommand(command: string, template: GoalTemplate, cwd: string): string {
+	try {
+		const output = execFileSync("/bin/bash", ["-lc", command], {
+			cwd,
+			encoding: "utf8",
+			timeout: template.commandTimeoutMs,
+			maxBuffer: template.commandOutputLimit + 1024,
+		});
+		return output.length > template.commandOutputLimit ? `${output.slice(0, template.commandOutputLimit)}\n[output truncated]` : output;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Inline command failed in template ${template.name}: ${message}`);
+	}
+}
+
+function stripMarkdownExt(path: string): string {
+	return path.replace(/\.(md|markdown|txt)$/i, "");
+}
+
+function parseList(value?: string): string[] {
+	if (!value) return [];
+	return value.replace(/^\[|\]$/g, "").split(",").map((item) => stripQuotes(item.trim())).filter(Boolean);
+}
+
+function parseBoolean(value?: string): boolean {
+	return value === "true" || value === "yes" || value === "1";
+}
+
+function parsePositiveInt(value: string | undefined, fallback: number): number {
+	const parsed = Number(value);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function firstContentLine(body: string): string | undefined {
+	return body.split(/\r?\n/).map((line) => line.replace(/^#+\s*/, "").trim()).find(Boolean);
+}
+
+function stripQuotes(value: string): string {
+	return value.replace(/^['"]|['"]$/g, "");
+}
+
+function unquote(value: string): string {
+	return stripQuotes(value);
+}

package/.pi/extensions/goal/tools.ts

@@ -0,0 +1,279 @@
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatElapsed, validateObjective } from "./format";
+import { isBudgetExhausted } from "./budget";
+import { createTelemetry, noteBudgetLimit } from "./telemetry";
+import { createGoalState, getGoal, getTelemetry, persistClearGoal, persistSetGoal, persistUpdateGoal } from "./state";
+import { syncGoalUi } from "./ui";
+import type { GoalCommandScheduler, GoalContinuationCanceller, GoalMonitorCanceller, GoalMonitorScheduler, GoalState, GoalStatus, GoalTelemetrySnapshot } from "./types";
+
+const EmptyParams = Type.Object({});
+const CreateGoalParams = Type.Object({
+	objective: Type.String({ description: "Goal objective explicitly requested by the user" }),
+	token_budget: Type.Optional(Type.Number({ description: "Optional positive token budget" })),
+	time_budget_seconds: Type.Optional(Type.Number({ description: "Optional positive time budget in seconds" })),
+});
+const NullableNumber = Type.Union([Type.Number(), Type.Null()]);
+const UpdateGoalParams = Type.Object({
+	status: Type.Optional(Type.String({ description: "Optional status update: active, paused, or complete" })),
+	objective: Type.Optional(Type.String({ description: "Optional replacement objective explicitly requested by the user" })),
+	token_budget: Type.Optional(NullableNumber),
+	time_budget_seconds: Type.Optional(NullableNumber),
+});
+
+type ToolDetails = {
+	goal: GoalState | null;
+	telemetry?: GoalTelemetrySnapshot | null;
+	remaining_tokens?: number;
+	remaining_time_seconds?: number;
+	completion_budget_report?: string;
+	error?: string;
+};
+
+type GoalToolRuntime = {
+	scheduleContinuation?: GoalCommandScheduler;
+	cancelContinuation?: GoalContinuationCanceller;
+	scheduleMonitor?: GoalMonitorScheduler;
+	cancelMonitor?: GoalMonitorCanceller;
+};
+
+export function registerGoalTools(
+	pi: ExtensionAPI,
+	scheduleContinuation?: GoalCommandScheduler,
+	cancelContinuation?: GoalContinuationCanceller,
+	scheduleMonitor?: GoalMonitorScheduler,
+	cancelMonitor?: GoalMonitorCanceller,
+): void {
+	const runtime: GoalToolRuntime = { scheduleContinuation, cancelContinuation, scheduleMonitor, cancelMonitor };
+	registerGetGoalTool(pi);
+	registerCreateGoalTool(pi, runtime);
+	registerUpdateGoalTool(pi, runtime);
+	registerClearGoalTool(pi, runtime);
+}
+
+function registerGetGoalTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "get_goal",
+		label: "Get Goal",
+		description: "Get the current pi-goal state, including status, budget, token usage, and time usage.",
+		promptSnippet: "Inspect the active pi-goal objective and progress state.",
+		promptGuidelines: ["Use get_goal to inspect an explicit active goal before deciding whether it is complete."],
+		parameters: EmptyParams,
+		async execute() {
+			return resultForGoal(getGoal(), getTelemetry());
+		},
+	});
+}
+
+function registerCreateGoalTool(pi: ExtensionAPI, runtime: GoalToolRuntime): void {
+	pi.registerTool({
+		name: "create_goal",
+		label: "Create Goal",
+		description: "Create a new pi-goal only when the user explicitly asks for a persistent goal.",
+		promptSnippet: "Create an explicit persistent pi-goal when requested.",
+		promptGuidelines: [
+			"Use create_goal only when the user explicitly asks to create or pursue a persistent goal.",
+			"Do not infer goals from ordinary tasks; normal user requests are not automatically pi-goals.",
+		],
+		parameters: CreateGoalParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return createGoalFromTool(pi, runtime, params, ctx);
+		},
+	});
+}
+
+function registerUpdateGoalTool(pi: ExtensionAPI, runtime: GoalToolRuntime): void {
+	pi.registerTool({
+		name: "update_goal",
+		label: "Update Goal",
+		description: "Update the current pi-goal when the user explicitly asks to edit, pause, resume, or complete it.",
+		promptSnippet: "Update an explicit pi-goal field or status when requested by the user.",
+		promptGuidelines: updateGoalGuidelines(),
+		parameters: UpdateGoalParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return updateGoalFromTool(pi, runtime, params, ctx);
+		},
+	});
+}
+
+function registerClearGoalTool(pi: ExtensionAPI, runtime: GoalToolRuntime): void {
+	pi.registerTool({
+		name: "clear_goal",
+		label: "Clear Goal",
+		description: "Clear the current pi-goal when the user explicitly asks to remove the persistent goal or hide the goal widget.",
+		promptSnippet: "Clear the explicit persistent pi-goal when requested by the user.",
+		promptGuidelines: [
+			"Use clear_goal only when the user explicitly asks to clear, remove, delete, or dismiss the current goal.",
+			"Do not clear a goal merely because it is complete unless the user asks to clear it.",
+		],
+		parameters: EmptyParams,
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const goal = getGoal();
+			runtime.cancelContinuation?.(goal?.goalId, "tool-clear");
+			runtime.cancelMonitor?.(goal?.goalId, "tool-clear");
+			persistClearGoal(pi, "tool");
+			syncGoalUi(ctx, null);
+			return resultForGoal(null, getTelemetry(), goal ? "Goal cleared." : "No goal was set.");
+		},
+	});
+}
+
+function updateGoalGuidelines(): string[] {
+	return [
+		"Use update_goal with status complete only after verifying the goal objective is actually achieved.",
+		"Use update_goal for objective or budget edits only when the user explicitly asks to modify the persistent goal.",
+		"Use status paused or active only when the user explicitly asks to pause or resume the goal.",
+		"Do not infer goal edits from ordinary task discussion.",
+		"Use clear_goal, not update_goal, when the user asks to clear/remove the current goal.",
+	];
+}
+
+type CreateGoalInput = {
+	objective: string;
+	token_budget?: number;
+	time_budget_seconds?: number;
+};
+
+type UpdateGoalInput = {
+	status?: string;
+	objective?: string;
+	token_budget?: number | null;
+	time_budget_seconds?: number | null;
+};
+
+type GoalUpdateResult = { ok: true; goal: GoalState; prefix: string; budgetChanged?: boolean } | { ok: false; error: string };
+
+function createGoalFromTool(pi: ExtensionAPI, runtime: GoalToolRuntime, params: CreateGoalInput, ctx: ExtensionContext) {
+	if (getGoal()) return errorResult("A goal already exists. Use clear_goal or ask the user before replacing it.");
+	const validation = validateObjective(params.objective);
+	if (!validation.ok) return errorResult(validation.hint ? `${validation.message} ${validation.hint}` : validation.message);
+	const budgetError = validateBudgets(params.token_budget, params.time_budget_seconds);
+	if (budgetError) return errorResult(budgetError);
+	const goal = createGoalState(validation.objective, params.token_budget, params.time_budget_seconds);
+	const telemetry = createTelemetry(goal.goalId, goal.createdAt);
+	persistSetGoal(pi, goal, telemetry, "tool");
+	syncGoalUi(ctx, goal);
+	runtime.scheduleMonitor?.(ctx);
+	return resultForGoal(goal, telemetry, "Goal created.");
+}
+
+function updateGoalFromTool(pi: ExtensionAPI, runtime: GoalToolRuntime, params: UpdateGoalInput, ctx: ExtensionContext) {
+	const goal = getGoal();
+	if (!goal) return errorResult("No goal exists to update.");
+	const update = buildGoalUpdate(goal, params);
+	if (!update.ok) return errorResult(update.error);
+	if (update.goal.status !== "active") {
+		runtime.cancelContinuation?.(goal.goalId, "tool-status");
+		runtime.cancelMonitor?.(goal.goalId, "tool-status");
+	}
+	persistUpdateGoal(pi, update.goal, telemetryForUpdate(update.goal), "tool");
+	syncGoalUi(ctx, update.goal);
+	if (goal.status !== "active" && update.goal.status === "active") {
+		runtime.scheduleMonitor?.(ctx);
+		runtime.scheduleContinuation?.(ctx, "resumed");
+	}
+	return resultForGoal(update.goal, getTelemetry(), update.prefix);
+}
+
+function validateBudgets(tokenBudget?: number, timeBudgetSeconds?: number): string | undefined {
+	if (tokenBudget !== undefined && (!Number.isInteger(tokenBudget) || tokenBudget <= 0)) return "token_budget must be a positive integer when provided.";
+	if (timeBudgetSeconds !== undefined && (!Number.isInteger(timeBudgetSeconds) || timeBudgetSeconds <= 0)) {
+		return "time_budget_seconds must be a positive integer when provided.";
+	}
+	return undefined;
+}
+
+function buildGoalUpdate(goal: GoalState, params: UpdateGoalInput): GoalUpdateResult {
+	let next: GoalState = { ...goal };
+	const changes: string[] = [];
+	const objectiveResult = applyObjectiveUpdate(next, params.objective, changes);
+	if (!objectiveResult.ok) return objectiveResult;
+	next = objectiveResult.goal;
+	const budgetResult = applyBudgetUpdates(next, params, changes);
+	if (!budgetResult.ok) return budgetResult;
+	next = budgetResult.budgetChanged && params.status === undefined ? recomputeStatusAfterBudgetEdit(budgetResult.goal) : budgetResult.goal;
+	if (params.status !== undefined) {
+		const status = parseToolStatus(params.status);
+		if (!status) return { ok: false, error: "status must be active, paused, or complete when provided." };
+		next = { ...next, status };
+		changes.push(`status ${status}`);
+	}
+	if (changes.length === 0) return { ok: false, error: "No goal updates were provided." };
+	return { ok: true, goal: { ...next, updatedAt: Date.now() }, prefix: next.status === "complete" ? "Goal achieved." : `Goal updated: ${changes.join(", ")}.` };
+}
+
+function applyObjectiveUpdate(goal: GoalState, objective: string | undefined, changes: string[]): GoalUpdateResult {
+	if (objective === undefined) return { ok: true, goal, prefix: "" };
+	const validation = validateObjective(objective);
+	if (!validation.ok) return { ok: false, error: validation.hint ? `${validation.message} ${validation.hint}` : validation.message };
+	changes.push("objective");
+	return { ok: true, goal: { ...goal, objective: validation.objective }, prefix: "" };
+}
+
+function applyBudgetUpdates(goal: GoalState, params: UpdateGoalInput, changes: string[]): GoalUpdateResult {
+	let next = goal;
+	let budgetChanged = false;
+	if (params.token_budget !== undefined) {
+		if (params.token_budget !== null && (!Number.isInteger(params.token_budget) || params.token_budget <= 0)) return { ok: false, error: "token_budget must be a positive integer or null when provided." };
+		next = { ...next, tokenBudget: params.token_budget === null ? undefined : params.token_budget };
+		changes.push("token budget");
+		budgetChanged = true;
+	}
+	if (params.time_budget_seconds !== undefined) {
+		if (params.time_budget_seconds !== null && (!Number.isInteger(params.time_budget_seconds) || params.time_budget_seconds <= 0)) return { ok: false, error: "time_budget_seconds must be a positive integer or null when provided." };
+		next = { ...next, timeBudgetSeconds: params.time_budget_seconds === null ? undefined : params.time_budget_seconds };
+		changes.push("time budget");
+		budgetChanged = true;
+	}
+	return { ok: true, goal: next, prefix: "", budgetChanged };
+}
+
+function recomputeStatusAfterBudgetEdit(goal: GoalState): GoalState {
+	if (goal.status !== "active" && goal.status !== "budgetLimited") return goal;
+	return isBudgetExhausted(goal) ? { ...goal, status: "budgetLimited" } : { ...goal, status: "active" };
+}
+
+function telemetryForUpdate(goal: GoalState): GoalTelemetrySnapshot | null {
+	const reason = isBudgetExhausted(goal);
+	if (goal.status === "budgetLimited" && reason) return noteBudgetLimit(getTelemetry(), reason);
+	return getTelemetry();
+}
+
+function parseToolStatus(status: string): GoalStatus | undefined {
+	if (status === "active" || status === "paused" || status === "complete") return status;
+	return undefined;
+}
+
+function resultForGoal(goal: GoalState | null, telemetry: GoalTelemetrySnapshot | null, prefix?: string) {
+	const details: ToolDetails = { goal, telemetry, remaining_tokens: remainingTokens(goal), remaining_time_seconds: remainingTime(goal) };
+	if (goal?.status === "complete" && (goal.tokenBudget !== undefined || goal.timeBudgetSeconds !== undefined)) {
+		details.completion_budget_report = `Goal achieved. Report final budget usage to the user: tokens used: ${goal.tokensUsed}${goal.tokenBudget === undefined ? "" : ` of ${goal.tokenBudget}`}; time used: ${goal.timeUsedSeconds}${goal.timeBudgetSeconds === undefined ? "" : ` of ${goal.timeBudgetSeconds}`} seconds.`;
+	}
+	return { content: [{ type: "text" as const, text: `${prefix ? `${prefix}\n` : ""}${formatToolGoal(goal)}` }], details };
+}
+
+function errorResult(error: string) {
+	return { content: [{ type: "text" as const, text: `Error: ${error}` }], details: { goal: getGoal(), telemetry: getTelemetry(), error } as ToolDetails };
+}
+
+function remainingTokens(goal: GoalState | null): number | undefined {
+	return goal?.tokenBudget === undefined ? undefined : Math.max(0, goal.tokenBudget - goal.tokensUsed);
+}
+
+function remainingTime(goal: GoalState | null): number | undefined {
+	return goal?.timeBudgetSeconds === undefined ? undefined : Math.max(0, goal.timeBudgetSeconds - goal.timeUsedSeconds);
+}
+
+function formatToolGoal(goal: GoalState | null): string {
+	if (!goal) return "No goal is currently set.";
+	const tokenBudget = goal.tokenBudget === undefined ? "none" : `${goal.tokenBudget} (${remainingTokens(goal)} remaining)`;
+	const timeBudget = goal.timeBudgetSeconds === undefined ? "none" : `${formatElapsed(goal.timeBudgetSeconds)} (${remainingTime(goal)} seconds remaining)`;
+	return [
+		`Goal: ${goal.status}`,
+		`Objective: ${goal.objective}`,
+		`Time used: ${goal.timeUsedSeconds} seconds`,
+		`Tokens used: ${goal.tokensUsed}`,
+		`Token budget: ${tokenBudget}`,
+		`Time budget: ${timeBudget}`,
+	].join("\n");
+}