pi-better-goal 0.6.0 → 0.7.0

package/README.md

@@ -13,11 +13,12 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal, and it stays paused while you talk to the agent. Say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows `goal paused · say "go" or /goal resume`, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
+- `/goal settings` opens an interactive settings page in the TUI. Select a row with Up/Down and toggle with Space/Enter; changes save immediately, and Escape closes the page. Both controls default to `on`. Automatic continuation controls idle and background-drain wakes; conversational resume controls the agent's Escape-pause resume tool. Goal kickoff, `/goal resume`, and `alt+g` remain available with either control off. For scripts or non-interactive sessions, use `/goal settings auto-continue on|off` and `/goal settings conversational-resume on|off`; bare `/goal settings` prints the saved values outside the TUI.
+- `escape` pauses the active goal, and it stays paused while you talk to the agent. With conversational resume enabled, say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows the available resume path, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
-- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (30s through 300s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
+- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
 - An observable-progress stall state for active goals.
 
 ## Skill-Owned Workflows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -3,6 +3,8 @@ import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 import { commandAvailable, commandInvocation, resolveGoalCommand } from "./command-binding.js";
+import { goalPreferencesPath, readGoalPreferences, writeGoalPreference, type GoalPreferences } from "./preferences.js";
+import { createGoalSettingsPage } from "./settings-page.js";
 
 import {
   collectActivitySnapshot,
@@ -50,7 +52,7 @@ import {
 } from "./types.js";
 
 const POLL_INTERVAL_MS = 2_000;
-const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 30_000;
+const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 60_000;
 const DEFAULT_MAX_NO_PROGRESS_RETRIES = 10;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const WAKE_DISABLED =
@@ -82,20 +84,20 @@ const GOAL_RESUME_RULE =
   "or answers a decision you explicitly asked for in your previous message with a choice that means proceed. Never call it for questions, \"why...\", \"what about...\", \"let me think\", or discussion.";
 
 /** True when the agent may resume this goal with `goal_resume`. */
-export function agentResumable(goal: GoalSnapshot | null): boolean {
-  return goal?.status === "paused" && goal.pauseReason === "interrupt";
+export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
+  return conversationalResume && goal?.status === "paused" && goal.pauseReason === "interrupt";
 }
 
 /** Footer status for a paused goal, telling the user how to resume it. */
-export function pausedGoalStatus(goal: GoalSnapshot): string {
-  return agentResumable(goal) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
+export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true): string {
+  return agentResumable(goal, conversationalResume) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
 }
 
-function pausedGoalPrompt(goal: GoalSnapshot): string {
+function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
   return [
     `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
     "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
-    GOAL_RESUME_RULE,
+    conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
 }
 
@@ -106,10 +108,21 @@ const GOAL_ACTIONS: readonly AutocompleteItem[] = [
   { value: "resume", label: "resume", description: "Resume the paused goal" },
   { value: "clear", label: "clear", description: "Remove the current goal" },
   { value: "complete", label: "complete", description: "Mark the current goal complete" },
+  { value: "settings", label: "settings", description: "Inspect or persist goal continuation and conversational resume controls" },
 ];
 
+const GOAL_SETTINGS = ["auto-continue", "conversational-resume"] as const;
+
 export function goalArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
   const prefix = argumentPrefix.trimStart().toLowerCase();
+  if (prefix.startsWith("settings ")) {
+    const settingPrefix = prefix.slice("settings ".length);
+    const choices = GOAL_SETTINGS.flatMap((setting) => settingPrefix.startsWith(`${setting} `)
+      ? ["on", "off"].map((mode) => `settings ${setting} ${mode}`)
+      : [`settings ${setting}`]);
+    const matches = choices.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+    return matches.length > 0 ? matches : null;
+  }
   const matches = GOAL_ACTIONS.filter((action) => action.value.startsWith(prefix));
   return matches.length > 0 ? [...matches] : null;
 }
@@ -124,7 +137,7 @@ function parseDurationEnv(raw: string | undefined, fallback: number): number {
 
 /**
  * Linear backoff for no-progress retries: each identical outcome waits one more
- * grace period than the last (30s, 60s, 90s, ... by default).
+ * grace period than the last (60s, 120s, 180s, ... by default).
  */
 export function idleContinuationDelay(noProgressRetries: number, baseMs = IDLE_CONTINUATION_DELAY_MS): number {
   return Math.min(MAX_TIMER_DELAY_MS, baseMs * (1 + Math.max(0, noProgressRetries)));
@@ -214,9 +227,11 @@ function formatGoal(
   goal: GoalSnapshot | null,
   continuation: ReturnType<typeof currentContinuationState> = null,
   stall = observeGoalStall(goal, continuation),
+  preferences: GoalPreferences = { autoContinue: true, conversationalResume: true },
 ): string {
+  const settings = formatPreferences(preferences);
   if (!goal) {
-    return "No goal is set.";
+    return `No goal is set.\n${settings}`;
   }
   const budget = goal.tokenBudget === null ? "none" : String(goal.tokenBudget);
   const timing = goalTiming(goal);
@@ -232,14 +247,22 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    settings,
     ...(goal.status === "paused"
-      ? [agentResumable(goal)
+      ? [agentResumable(goal, preferences.conversationalResume)
         ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
         : "Resume: /goal resume or alt+g"]
       : []),
   ].join("\n");
 }
 
+function formatPreferences(preferences: GoalPreferences): string {
+  return [
+    `Automatic continuation setting: ${preferences.autoContinue ? "on" : "off"}${WAKE_DISABLED ? " (disabled by environment)" : ""}`,
+    `Conversational resume setting: ${preferences.conversationalResume ? "on" : "off"}`,
+  ].join("\n");
+}
+
 function formatSnapshot(snapshot: ActivitySnapshot): string {
   const providers = snapshot.providers.map((provider) => {
     const active = provider.items.filter((item) => item.active).length;
@@ -284,6 +307,7 @@ export default function (pi: ExtensionAPI): void {
   let idleContinuationSignature = "";
   let refreshGoalWidget: ((force?: boolean) => void) | undefined;
   let lastAgentEvidence: ContinuationEvidence | null = null;
+  let preferences: GoalPreferences = { autoContinue: true, conversationalResume: true };
   /** Background items active when each pending blocking question started, keyed by tool call id. */
   const pendingQuestions = new Map<string, Map<string, BackgroundWorkItem>>();
 
@@ -387,7 +411,9 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
+    notifyGoal(ctx, preferences.conversationalResume
+      ? 'Goal paused. Say "go" to resume it, or use /goal resume.'
+      : "Goal paused. Use /goal resume or alt+g to resume it.");
   };
 
   /** Why a paused goal cannot become active again, or null when it can. */
@@ -470,7 +496,7 @@ export default function (pi: ExtensionAPI): void {
     kind: "continuation" | "background-drained",
     snapshot?: ActivitySnapshot,
   ): void => {
-    if (WAKE_DISABLED || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
+    if (WAKE_DISABLED || !preferences.autoContinue || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
     }
     if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
@@ -500,7 +526,7 @@ export default function (pi: ExtensionAPI): void {
     const execution = executionGeneration;
     const wake = wakeGeneration;
     const auditIsCurrent = (): boolean => {
-      if (execution !== executionGeneration || wake !== wakeGeneration) return false;
+      if (WAKE_DISABLED || !preferences.autoContinue || execution !== executionGeneration || wake !== wakeGeneration) return false;
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
@@ -603,7 +629,7 @@ export default function (pi: ExtensionAPI): void {
     const background = snapshot?.backgroundRunning
       ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
       : undefined;
-    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal)} · ${background}` : pausedGoalStatus(goal);
+    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal, preferences.conversationalResume)} · ${background}` : pausedGoalStatus(goal, preferences.conversationalResume);
     if (background) return background;
     const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
     if (continuation?.blocked) return "waiting: no progress";
@@ -633,7 +659,7 @@ export default function (pi: ExtensionAPI): void {
     if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
     try {
       const active = pi.getActiveTools();
-      const wanted = agentResumable(goal);
+      const wanted = agentResumable(goal, preferences.conversationalResume);
       if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
       pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
     } catch {
@@ -760,17 +786,57 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("goal", {
-    description: "Create, inspect, pause, resume, clear, or complete the active goal",
+    description: "Create, inspect, pause, resume, clear, or complete the active goal; configure persistent goal settings",
     getArgumentCompletions: goalArgumentCompletions,
     handler: async (args, ctx) => {
       currentCtx = ctx;
       const trimmed = args.trim();
       const current = getGoal(ctx);
 
+      if (trimmed === "settings" || trimmed.startsWith("settings ")) {
+        const changePreference = async (key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
+          const previous = preferences;
+          preferences = writeGoalPreference(key, enabled);
+          if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
+          syncResumeTool(getGoal(ctx));
+          applyStatus(ctx);
+          if (!previous.autoContinue && preferences.autoContinue) {
+            const snapshot = await publishSnapshot(ctx);
+            const goal = getGoal(ctx);
+            if (snapshot && isPokeable(goal) && !isForegroundBusy(ctx) && !snapshot.backgroundRunning) {
+              scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+            }
+          }
+        };
+        if (trimmed === "settings" && ctx.hasUI && ctx.mode !== "rpc" && typeof ctx.ui.custom === "function") {
+          await ctx.ui.custom<void>((tui, theme, _kb, done) => createGoalSettingsPage(theme, {
+            get: () => ({ ...preferences }),
+            change: changePreference,
+          }, () => tui.requestRender(), () => done()));
+          return;
+        }
+        const [, setting, mode, ...extra] = trimmed.split(/\s+/);
+        if (setting !== undefined && (!GOAL_SETTINGS.includes(setting as typeof GOAL_SETTINGS[number]) ||
+            (mode !== "on" && mode !== "off") || extra.length > 0)) {
+          notifyGoal(ctx, "Usage: /goal settings [auto-continue|conversational-resume on|off]", "warning");
+          return;
+        }
+        if (setting !== undefined) {
+          try {
+            await changePreference(setting === "auto-continue" ? "autoContinue" : "conversationalResume", mode === "on");
+          } catch (error) {
+            notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+            return;
+          }
+        }
+        ctx.ui.notify(`${formatPreferences(preferences)}\nPreferences: ${goalPreferencesPath()}`, "info");
+        return;
+      }
+
       if (!trimmed) {
         const continuation = current ? currentContinuationState(ctx, current.goalId) : null;
         // Inspection is always explicit user intent; show the full summary even while busy.
-        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning })), "info");
+        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning }), preferences), "info");
         return;
       }
 
@@ -847,8 +913,8 @@ export default function (pi: ExtensionAPI): void {
         backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
       });
       return {
-        content: [{ type: "text", text: formatGoal(goal, continuation, stall) }],
-        details: { goal, continuation, stall, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+        content: [{ type: "text", text: formatGoal(goal, continuation, stall, preferences) }],
+        details: { goal, continuation, stall, preferences: { ...preferences }, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
       };
     },
   });
@@ -904,7 +970,13 @@ export default function (pi: ExtensionAPI): void {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const reason = (params as { reason?: string }).reason;
       const current = getGoal(ctx);
-      if (!agentResumable(current)) {
+      if (!preferences.conversationalResume) {
+        return {
+          content: [{ type: "text", text: "Conversational goal resume is disabled. Only the user can resume with /goal resume or alt+g." }],
+          details: { ok: false, goal: current },
+        };
+      }
+      if (!agentResumable(current, preferences.conversationalResume)) {
         const text = current?.status === "paused"
           ? "This goal was paused with /goal pause or by the runtime. Only the user can resume it, with /goal resume."
           : "No goal is paused, so there is nothing to resume.";
@@ -996,6 +1068,11 @@ export default function (pi: ExtensionAPI): void {
     collectionPending = false;
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    try {
+      preferences = readGoalPreferences();
+    } catch (error) {
+      notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+    }
     const restoredGoal = getGoal(ctx);
     if (restoredGoal?.status === "active" && !restoredGoal.command && skillCommandName(restoredGoal.objective)) {
       setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
@@ -1046,7 +1123,8 @@ export default function (pi: ExtensionAPI): void {
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
-    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
+    const pausedInstruction = goal?.status === "paused" && goal.pauseReason === "interrupt"
+      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "";
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }

package/src/preferences.ts

@@ -0,0 +1,70 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface GoalPreferences {
+  autoContinue: boolean;
+  conversationalResume: boolean;
+}
+
+export interface GoalPreferenceSeams {
+  agentDir?: () => string;
+}
+
+export function goalPreferencesPath(seams: GoalPreferenceSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "extensions", "pi-better-goal-preferences.json");
+}
+
+export function readGoalPreferences(seams: GoalPreferenceSeams = {}): GoalPreferences {
+  const path = goalPreferencesPath(seams);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { autoContinue: true, conversationalResume: true };
+    }
+    throw new Error(`Goal preferences at ${path} could not be read: ${messageOf(error)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Goal preferences at ${path} are not valid JSON: ${messageOf(error)}`);
+  }
+  const value = parsed as Partial<GoalPreferences> & { version?: unknown } | null;
+  if (value?.version !== 1 ||
+      (value.autoContinue !== undefined && typeof value.autoContinue !== "boolean") ||
+      (value.conversationalResume !== undefined && typeof value.conversationalResume !== "boolean")) {
+    throw new Error(`Goal preferences at ${path} must contain version 1 and boolean autoContinue/conversationalResume settings.`);
+  }
+  return {
+    autoContinue: value.autoContinue ?? true,
+    conversationalResume: value.conversationalResume ?? true,
+  };
+}
+
+/** Persist one control without replacing the other session's saved choice. */
+export function writeGoalPreference(
+  key: keyof GoalPreferences,
+  enabled: boolean,
+  seams: GoalPreferenceSeams = {},
+): GoalPreferences {
+  const preferences = { ...readGoalPreferences(seams), [key]: enabled };
+  const path = goalPreferencesPath(seams);
+  const pending = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(pending, `${JSON.stringify({ version: 1, ...preferences }, null, 2)}\n`, "utf8");
+    renameSync(pending, path);
+  } catch (error) {
+    throw new Error(`Goal preferences at ${path} could not be written: ${messageOf(error)}`);
+  } finally {
+    rmSync(pending, { force: true });
+  }
+  return preferences;
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/settings-page.ts

@@ -0,0 +1,67 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type Component, type Focusable } from "@earendil-works/pi-tui";
+import type { GoalPreferences } from "./preferences.js";
+
+const rows: { key: keyof GoalPreferences; label: string }[] = [
+  { key: "autoContinue", label: "Automatic continuation" },
+  { key: "conversationalResume", label: "Conversational resume" },
+];
+
+export function createGoalSettingsPage(
+  theme: Theme,
+  handlers: { get(): GoalPreferences; change(key: keyof GoalPreferences, enabled: boolean): Promise<void> },
+  requestRender: () => void,
+  close: () => void,
+): Component & Focusable {
+  let row = 0;
+  let busy = false;
+  let message = "";
+  let error = false;
+  function change(): void {
+    const selected = rows[row]!;
+    busy = true;
+    message = "Saving...";
+    error = false;
+    void Promise.resolve().then(() => handlers.change(selected.key, !handlers.get()[selected.key])).then(() => {
+      message = "Saved.";
+    }, (cause: unknown) => {
+      message = cause instanceof Error ? cause.message : String(cause);
+      error = true;
+    }).finally(() => {
+      busy = false;
+      requestRender();
+    });
+  }
+  return {
+    focused: false,
+    invalidate() {},
+    handleInput(data: string) {
+      if (matchesKey(data, Key.escape)) { close(); return; }
+      if (busy) return;
+      if (matchesKey(data, Key.up)) row = Math.max(0, row - 1);
+      else if (matchesKey(data, Key.down)) row = Math.min(rows.length - 1, row + 1);
+      else if (matchesKey(data, Key.enter) || data === " ") change();
+      requestRender();
+    },
+    render(width: number) {
+      const w = Math.max(1, Math.floor(width));
+      const preferences = handlers.get();
+      const lines = [theme.fg("accent", theme.bold("  Goal settings")), ""];
+      rows.forEach(({ key, label }, index) => {
+        const selected = row === index;
+        const title = theme.fg(selected ? "accent" : "text", (selected ? "> " : "  ") + label);
+        const value = preferences[key] ? "On" : "Off";
+        const active = selected ? theme.inverse(value) : theme.fg("text", value);
+        if (w < 40) {
+          lines.push(title, "  " + active);
+        } else {
+          const line = title + " ".repeat(Math.max(1, 30 - visibleWidth(title))) + active;
+          lines.push(selected ? theme.bg("selectedBg", theme.bold(line)) : line);
+        }
+      });
+      if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
+      lines.push("", theme.fg("dim", "Up/Down Select · Space/Enter Toggle · Esc Back"));
+      return lines.map((line) => truncateToWidth(line, w, ""));
+    },
+  };
+}