pi-better-goal 0.10.3 → 0.11.0

package/README.md

@@ -14,7 +14,7 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
 - `/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. All three controls default to `on`. Automatic continuation controls idle and background-drain wakes; conversational resume controls the agent's Escape-pause resume tool; **Pause on Esc** controls whether editor Escape pauses the active goal. Goal kickoff, `/goal resume`, and `alt+g` remain available with these controls off. For scripts or non-interactive sessions, use `/goal settings auto-continue on|off`, `/goal settings conversational-resume on|off`, and `/goal settings pause-on-escape on|off`; bare `/goal settings` prints the saved values outside the TUI.
-- `escape` pauses the active goal by default, and it stays paused while you talk to the agent. With **Pause on Esc** off, observed editor Escape leaves the goal active while preserving native streaming interruption and menu/dialog cancellation. Automatic continuation remains independent. Hosts without terminal/focus inspection and unknown custom editors retain generic abort-to-pause behavior because they cannot identify Escape reliably. 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.
+- `escape` pauses the active goal by default, and it stays paused while you talk to the agent. With **Pause on Esc** off, observed editor Escape leaves the goal active while preserving native streaming interruption and menu/dialog cancellation. Automatic continuation remains independent. Hosts without terminal/focus inspection and unknown custom editors retain generic abort-to-pause behavior because they cannot identify Escape reliably. 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`. 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.

package/package.json

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

package/src/index.ts

@@ -38,6 +38,7 @@ import {
   renderGoalClockLine,
 } from "./goal-clock.js";
 import { createRenderScheduler } from "./shared-render-scheduler.js";
+import { initializeNavigatorPanels, setNavigatorPanel } from "./shared-navigator-panels.js";
 import { collectSubagentActivity } from "./subagents.js";
 import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
 import { completionGate, pauseGate, schedulerWaitUntil } from "./workflow-gates.js";
@@ -301,6 +302,7 @@ function formatSnapshot(snapshot: ActivitySnapshot): string {
 }
 
 export default function (pi: ExtensionAPI): void {
+  initializeNavigatorPanels(pi);
   const providers = new Map<string, BackgroundActivityProvider>();
   const providerUnsubscribers = new Map<string, () => void>();
   providers.set("subagents", {
@@ -374,7 +376,7 @@ export default function (pi: ExtensionAPI): void {
    * Chat `notify` appends lines above the Working/bash status region. While the
    * agent is streaming, that height change desyncs Pi main-screen differential
    * rendering and stacks "Working..." / "Elapsed Xs" into scrollback. Keep
-   * mid-stream feedback out of the transcript; use the footer status instead.
+   * mid-stream non-error feedback out of the transcript.
    */
   const notifyGoal = (
     ctx: ExtensionContext,
@@ -385,11 +387,6 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     if (isForegroundBusy(ctx) && type !== "error") {
-      try {
-        ctx.ui.setStatus(EXTENSION_NAME, message);
-      } catch {
-        // Footer status is best-effort only.
-      }
       return;
     }
     ctx.ui.notify(message, type);
@@ -424,7 +421,6 @@ export default function (pi: ExtensionAPI): void {
     clearIdleContinuation();
     syncPollingState();
     syncResumeTool(goal);
-    applyStatus(ctx);
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
@@ -443,7 +439,6 @@ export default function (pi: ExtensionAPI): void {
     clearIdleContinuation();
     syncPollingState();
     syncResumeTool(null);
-    applyStatus(ctx);
     refreshGoalWidget?.(wasVisible);
   };
 
@@ -726,41 +721,9 @@ export default function (pi: ExtensionAPI): void {
       pi.events.emit(EVENT_TERMINAL_ATTENTION, snapshot);
       if (execution !== executionGeneration) return null;
     }
-    applyStatus(ctx);
-
     return snapshot;
   };
 
-  /** Footer status from the goal state and the latest activity snapshot. */
-  const statusText = (ctx: ExtensionContext, snapshot: ActivitySnapshot | null): string | undefined => {
-    const goal = getGoal(ctx);
-    let waitingOnAnswer = 0;
-    if (snapshot) {
-      for (const activeAtStart of pendingQuestions.values()) {
-        waitingOnAnswer += finishedSinceQuestion(activeAtStart, snapshot).length;
-      }
-    }
-    if (waitingOnAnswer > 0) return `${waitingOnAnswer} background done; waiting on your answer`;
-    if (goal?.status === "paused") return pausedGoalStatus(goal, preferences.conversationalResume);
-    if (snapshot?.backgroundRunning) return undefined;
-    const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
-    if (continuation?.blocked) return "waiting: no progress";
-    const goalStall = observeGoalStall(goal, continuation, {
-      foregroundRunning,
-      backgroundRunning: snapshot?.backgroundRunning ?? false,
-    });
-    return goalStall?.state === "stalled" ? "goal stalled" : undefined;
-  };
-
-  function applyStatus(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    try {
-      ctx.ui.setStatus(EXTENSION_NAME, statusText(ctx, latestSnapshot));
-    } catch {
-      // UI status is best-effort only.
-    }
-  }
-
   /**
    * `goal_resume` is in the model's tool list only while an escape-paused goal
    * waits. Pi activates newly registered tools by default, so this also removes
@@ -832,7 +795,8 @@ export default function (pi: ExtensionAPI): void {
     if (!ctx.hasUI) {
       return;
     }
-    ctx.ui.setWidget(
+    setNavigatorPanel(
+      ctx,
       EXTENSION_NAME,
       (tui, theme) => {
         const inputIsEditor = (): boolean => {
@@ -918,7 +882,6 @@ export default function (pi: ExtensionAPI): void {
     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);
@@ -1578,7 +1541,6 @@ export default function (pi: ExtensionAPI): void {
     if (blocked) {
       refreshGoalWidget?.();
       if (ctx.hasUI) {
-        ctx.ui.setStatus(EXTENSION_NAME, "waiting: no progress");
         ctx.ui.notify(
           `Goal automatic continuation is waiting after ${noProgressRetries} identical retries (${evidence.summary}). Use /goal resume or alt+g to resume it.`,
           "warning",
@@ -1630,8 +1592,7 @@ export default function (pi: ExtensionAPI): void {
     latestSnapshot = null;
     collectionPending = false;
     try {
-      ctx.ui.setStatus(EXTENSION_NAME, undefined);
-      ctx.ui.setWidget(EXTENSION_NAME, undefined);
+      setNavigatorPanel(ctx, EXTENSION_NAME, undefined);
     } catch {
       // Best-effort cleanup.
     }

package/src/shared-navigator-panels.ts

@@ -0,0 +1,250 @@
+// Generated from packages/navigator/panels.ts. Do not edit directly.
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { randomUUID } from "node:crypto";
+import { readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.js";
+
+export const NAVIGATOR_PANEL_WIDGET_KEY = "background-work-list";
+export const NAVIGATOR_ENTRY_TYPE = "pi-better-harness-navigator-panels";
+export const NAVIGATOR_STICKY_SETTING_ID = "navigator-sticky";
+type MouseEvent = { type: string; button: string; x: number; y: number; width: number; shift?: boolean; alt?: boolean; ctrl?: boolean };
+type PanelComponent = Component & { dispose?(): void; handleMouse?(event: MouseEvent): { handled: true; render: boolean } | undefined };
+export type NavigatorPanelFactory = (tui: TUI, theme: Theme) => PanelComponent;
+type Panel = { factory: NavigatorPanelFactory; component?: PanelComponent | undefined };
+type Preference = { version: 1; sticky: boolean };
+type Owner = { pi: ExtensionAPI; stop?: (() => void) | undefined };
+type State = {
+  panels: Map<string, Panel>;
+  owners: Map<ExtensionAPI, Owner>;
+  ctx?: ExtensionContext | undefined;
+  ui?: ExtensionContext["ui"] | undefined;
+  pi?: ExtensionAPI | undefined;
+  sticky: boolean;
+  mounted: boolean;
+  tui?: TUI | undefined;
+  theme?: Theme | undefined;
+  anchor?: string | undefined;
+  pendingAnchor: boolean;
+  generation: number;
+  ranges: Array<{ start: number; end: number; component: PanelComponent }>;
+  control?: { id: string; label: string; values: string[]; get(): string; change(value: string, ctx: ExtensionContext): void } | undefined;
+};
+const KEY = Symbol.for("pi-better-harness.navigator-panels.state");
+function state(): State {
+  const global = globalThis as typeof globalThis & { [KEY]?: State };
+  return global[KEY] ??= { panels: new Map(), owners: new Map(), sticky: true, mounted: false, pendingAnchor: false, generation: 0, ranges: [] };
+}
+function parsePreference(value: unknown): Preference {
+  if (value === undefined) return { version: 1, sticky: true };
+  const preference = value as Partial<Preference> | null;
+  if (!preference || preference.version !== 1 || typeof preference.sticky !== "boolean") {
+    throw new Error("Navigator preference must contain version 1 and a boolean sticky value.");
+  }
+  return { version: 1, sticky: preference.sticky };
+}
+function canScroll(pi: ExtensionAPI | undefined): boolean {
+  return typeof pi?.registerEntryRenderer === "function" && typeof pi?.appendEntry === "function";
+}
+function isTui(ctx: ExtensionContext | undefined): ctx is ExtensionContext {
+  return ctx?.mode === "tui" && ctx.hasUI && typeof ctx.ui?.setWidget === "function";
+}
+function disposePanels(s: State): void {
+  for (const panel of s.panels.values()) {
+    try { panel.component?.dispose?.(); } catch { /* stale UI cleanup is best effort */ }
+    panel.component = undefined;
+  }
+  s.ranges = [];
+}
+function orderedPanels(s: State): Panel[] {
+  const rank = (key: string) => key === "pi-better-goal" ? 0 : key === "pi-better-plan" ? 1 : 2;
+  return [...s.panels.entries()].sort(([a], [b]) => rank(a) - rank(b)).map(([, panel]) => panel);
+}
+function buildPanels(s: State): void {
+  if (!s.tui || !s.theme) return;
+  for (const panel of orderedPanels(s)) panel.component ??= panel.factory(s.tui, s.theme);
+}
+function renderPanels(s: State, width: number): string[] {
+  buildPanels(s);
+  const lines: string[] = [];
+  s.ranges = [];
+  for (const panel of orderedPanels(s)) {
+    if (!panel.component) continue;
+    const rendered = panel.component.render(width);
+    s.ranges.push({ start: lines.length, end: lines.length + rendered.length, component: panel.component });
+    lines.push(...rendered);
+  }
+  return lines;
+}
+function mouse(s: State, event: MouseEvent) {
+  const range = s.ranges.find(range => event.y >= range.start && event.y < range.end);
+  return range?.component.handleMouse?.({ ...event, y: event.y - range.start });
+}
+function restoreAnchor(ctx: ExtensionContext): string | undefined {
+  let anchor: string | undefined;
+  for (const entry of ctx.sessionManager?.getBranch?.() ?? []) {
+    if (entry.type !== "custom" || entry.customType !== NAVIGATOR_ENTRY_TYPE) continue;
+    const data = entry.data as { version?: unknown; anchor?: unknown } | undefined;
+    if (data?.version === 1 && typeof data.anchor === "string") anchor = data.anchor;
+  }
+  return anchor;
+}
+function appendAnchor(s: State): void {
+  if (s.sticky || s.anchor || !canScroll(s.pi)) return;
+  const anchor = randomUUID();
+  s.anchor = anchor;
+  try { s.pi!.appendEntry(NAVIGATOR_ENTRY_TYPE, { version: 1, anchor }); }
+  catch (error) { s.anchor = undefined; throw error; }
+}
+function scheduleAnchor(s: State): void {
+  if (s.anchor || s.pendingAnchor || s.sticky) return;
+  s.pendingAnchor = true;
+  const generation = s.generation;
+  // Session writes cannot run inside a component render. Empty sessions stay untouched.
+  queueMicrotask(() => {
+    if (generation !== s.generation) return;
+    s.pendingAnchor = false;
+    if (!s.sticky && s.panels.size) appendAnchor(s);
+  });
+}
+function clearHost(s: State): void {
+  s.generation++;
+  s.pendingAnchor = false;
+  try {
+    if (s.mounted && isTui(s.ctx)) s.ctx.ui.setWidget(NAVIGATOR_PANEL_WIDGET_KEY, undefined);
+  } catch { /* an old session context may already be detached */ }
+  disposePanels(s);
+  s.mounted = false;
+  s.tui = undefined;
+  s.theme = undefined;
+}
+function adoptContext(s: State, ctx: ExtensionContext): void {
+  if (s.ui && s.ui !== ctx.ui) {
+    clearHost(s);
+    s.panels.clear();
+    s.anchor = undefined;
+  }
+  s.ctx = ctx;
+  s.ui = ctx.ui;
+}
+function mountHost(s: State): void {
+  if (!isTui(s.ctx) || s.mounted || !s.panels.size) return;
+  s.mounted = true;
+  s.ctx.ui.setWidget(NAVIGATOR_PANEL_WIDGET_KEY, (tui, theme) => {
+    if (s.tui !== tui || s.theme !== theme) disposePanels(s);
+    s.tui = tui;
+    s.theme = theme;
+    buildPanels(s);
+    return {
+      render(width: number) {
+        const lines = renderPanels(s, width);
+        if (s.sticky) return lines;
+        if (lines.length) scheduleAnchor(s);
+        return [];
+      },
+      handleMouse: (event: MouseEvent) => s.sticky ? mouse(s, event) : undefined,
+      invalidate() {
+        for (const panel of s.panels.values()) panel.component?.invalidate();
+      },
+      dispose() { disposePanels(s); s.mounted = false; },
+    };
+  }, { placement: "aboveEditor" });
+}
+function changeSticky(value: string, ctx: ExtensionContext): void {
+  if (value !== "On" && value !== "Off") throw new Error("Sticky navigator expects On or Off.");
+  const s = state();
+  if (value === "Off" && !canScroll(s.pi)) {
+    throw new Error("Scrolling navigator requires a Pi version with registerEntryRenderer support.");
+  }
+  updateHarnessSetting("navigator", current => {
+    parsePreference(current);
+    return { version: 1, sticky: value === "On" };
+  });
+  adoptContext(s, ctx);
+  if (s.sticky && value === "Off") s.anchor = undefined;
+  s.sticky = value === "On";
+  refreshNavigatorPanels(ctx);
+}
+export function initializeNavigatorPanels(pi: ExtensionAPI): void {
+  const s = state();
+  if (s.owners.has(pi)) return;
+  s.pi = pi;
+  try { s.sticky = parsePreference(readHarnessSetting("navigator")).sticky; }
+  catch { s.sticky = true; }
+  if (!canScroll(pi)) s.sticky = true;
+  if (canScroll(pi)) pi.registerEntryRenderer(NAVIGATOR_ENTRY_TYPE, (entry) => {
+    const data = entry.data as { version?: number; anchor?: string } | undefined;
+    if (data?.version !== 1 || !data.anchor) return undefined;
+    // Pi reconstructs chat before session_start restores the visible branch.
+    // Keep the component mounted and resolve its active anchor at render time.
+    return {
+      render: width => !s.sticky && data.anchor === s.anchor ? renderPanels(s, width) : [],
+      handleMouse: event => !s.sticky && data.anchor === s.anchor ? mouse(s, event) : undefined,
+      invalidate() { for (const panel of s.panels.values()) panel.component?.invalidate(); },
+    } as PanelComponent;
+  });
+  s.control ??= {
+    id: NAVIGATOR_STICKY_SETTING_ID, label: "Sticky navigator", values: ["On", "Off"],
+    get: () => state().sticky ? "On" : "Off", change: changeSticky,
+  };
+  const owner: Owner = { pi };
+  s.owners.set(pi, owner);
+  // Use one stable contribution callback across vendored copies, but each owner
+  // cleans up its own event subscription when its extension is unloaded.
+  const register = () => pi.events?.emit?.("harness-settings:register", s.control);
+  owner.stop = pi.events?.on?.("harness-settings:request", register);
+  register();
+  pi.on("session_start", (_event, ctx) => {
+    adoptContext(s, ctx);
+    s.anchor = restoreAnchor(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    adoptContext(s, ctx);
+    s.anchor = restoreAnchor(ctx);
+    refreshNavigatorPanels(ctx);
+  });
+  pi.on("session_shutdown", () => {
+    owner.stop?.();
+    s.owners.delete(pi);
+    if (s.owners.size) return;
+    clearHost(s);
+    s.panels.clear();
+    s.anchor = undefined;
+    s.ctx = undefined;
+    s.ui = undefined;
+    s.pi = undefined;
+  });
+}
+export function setNavigatorPanel(
+  ctx: ExtensionContext, key: string, content: NavigatorPanelFactory | undefined,
+  _options?: { placement?: "aboveEditor" | "belowEditor" },
+): void {
+  const s = state();
+  if (!isTui(ctx)) return;
+  adoptContext(s, ctx);
+  s.panels.get(key)?.component?.dispose?.();
+  if (content) s.panels.set(key, { factory: content });
+  else s.panels.delete(key);
+  if (!s.panels.size) { clearHost(s); return; }
+  mountHost(s);
+  buildPanels(s);
+  s.tui?.requestRender?.();
+}
+export function refreshNavigatorPanels(ctx?: ExtensionContext): void {
+  const s = state();
+  if (ctx) adoptContext(s, ctx);
+  mountHost(s);
+  s.tui?.requestRender?.(true);
+}
+export function __resetNavigatorPanelsForTests(): void {
+  const s = state();
+  clearHost(s);
+  for (const owner of s.owners.values()) owner.stop?.();
+  s.owners.clear();
+  s.panels.clear();
+  s.pi = undefined;
+  s.ctx = undefined;
+  s.ui = undefined;
+  s.anchor = undefined;
+  s.sticky = true;
+  s.control = undefined;
+}