@hank-warren/pi-loop 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @hank-warren/pi-loop
 
+## 0.3.1
+
+### Patch Changes
+
+- 910f77a: stop invalidating the prompt cache, and stop re-sending the goal block every turn
+
+  Goal mode has to keep the objective and its rules in front of the model on every
+  turn. It did that twice: a full block appended to the system prompt with the
+  running budget counter embedded in it, and a near-complete copy re-sent as a
+  stored user message on every automatic continuation. pi-loop restated the
+  objective a third time in every poke.
+
+  Anthropic caches `tools → system → messages` as one prefix, so the moving budget
+  counter invalidated the system _and_ conversation cache on every turn of a
+  budgeted goal. Verified against the installed pi-ai Anthropic adapter
+  (`buildParams` places `cache_control` on the system block and the last user
+  message, and the `before_agent_start` append lands inside that cached block).
+
+  **Static per goal.** The system append is now byte-identical across turns of the
+  same goal and states only the budget _total_, so it changes only when the goal
+  does — start, edit, clear — which is one accepted cache rewrite per boundary.
+  Pinned as the cache-stability contract: same goal, different tokens used,
+  iteration, and elapsed time produce identical output.
+
+  **Dynamic per wake.** Kickoff, continuation, and poke messages shrink to
+  pointer-sized triggers carrying the continuation number, budget usage, and wake
+  reason, and point at the system prompt for the rest. Measured at ~4 chars/token:
+  kickoff 805 → 53, continuation 840 → 54, poke 86 → 64, system append 807 → 820
+  (+13 once per goal, the price of stability). Stored conversation tokens for a
+  25-iteration goal: 20,965 → 1,349. The resume, edit, and waiting-resume prompts
+  keep the full block — they are rare, user-initiated, and already a cache
+  boundary.
+
+  **Legibility.** Those messages now collapse to one-line transcript chips
+  (`⟳ goal continuation #4 · budget 12k/100k`, `⏰ loop wake 4/25 · stalled`) via
+  markdown transformers, which are display-only by Pi's contract: the stored
+  message and the model's context are untouched. New goal and loop widgets above
+  the editor carry the counters that left the system prompt — objective, budget
+  fraction, iteration, automatic turns for the goal; interval, iteration/cap, next
+  wake, and focus for the loop.
+
+  **Cross-extension assumption.** pi-loop's poke no longer restates the objective,
+  because loops require an active goal and pokes are ordinary user messages that
+  go through `before_agent_start`, so every poke turn already carries pi-goal's
+  system append. Documented in both READMEs; if pokes are ever delivered by a path
+  that bypasses that hook, the poke must carry the objective again.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -27,11 +27,15 @@ Each tick evaluates, in order:
 3. **Agent busy?** Never interrupt: coalesce into a single pending wake delivered at the next fully-settled idle boundary. N missed ticks collapse into one poke.
 4. **Goal state**: a missing goal (cleared mid-loop) **pauses** the loop; completion **stops** it — including through the clear that follows it, since pi-goal persists the finished goal and *then* clears the entry, so the newest entry at completion is a clear and the loop reads back past it; a safety pause (`paused`/`blocked`/`usage_limited`/`budget_limited`, or any unknown status) **pauses** it — pi-loop never pokes past pi-goal's circuit breakers. An `active` or `goal_wait`-waiting goal in an idle session is exactly the stall this extension exists for, so it pokes toward the goal (a tick is the external wake `goal_wait` arranges).
 5. **Iteration cap** (default 25 delivered pokes, `--max`/settings, explicit `unlimited` opt-in): stop.
-6. **Poke**: a goal wake message restating the goal (plus the loop focus, when set). Every poke carries a marker (`<!-- pi-loop-poke:<id>:<n> -->`) so a wakeup is identifiable as loop-injected rather than user-typed. The marker is **provenance only** — pi-loop coalesces wakes in its own state and never reads the marker back to drop a delivery.
+6. **Poke**: a goal wake message — the wake header, why it fired (stalled or the external wake for a waiting goal), and the loop focus when set. Every poke carries a marker (`<!-- pi-loop-poke:<id>:<n> -->`) so a wakeup is identifiable as loop-injected rather than user-typed. The marker is **provenance only** — pi-loop coalesces wakes in its own state and never reads the marker back to drop a delivery.
+
+**A poke does not restate the objective**, and this is a deliberate cross-extension assumption. Loops require an active goal, and pi-goal appends the objective, `goal_id`, and goal-mode rules to the system prompt of *every* goal turn — including poke turns, because pokes are delivered as ordinary user messages that go through `before_agent_start`. Restating the goal in the poke would store a duplicate copy in the conversation on every wake for no benefit. The token-lean contract is pinned in `test/messages.test.ts`; the matching cache-stability contract lives in [pi-goal](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-goal#fork-feature-cache-safe-token-lean-injections). If pokes are ever delivered by a path that bypasses `before_agent_start` (for example `pi.sendMessage({triggerTurn})`, which calls the agent directly), this assumption breaks and the poke must carry the objective again.
+
+In the transcript, a poke renders as a one-line chip (`⏰ loop wake 4/25 · stalled`) via a markdown transformer. That hook is display-only by Pi's contract — the stored message and the model's context are untouched.
 
 Expiry, completion, and pi-goal's safety states are also evaluated whenever the session settles, so a loop stops as soon as its goal does rather than at the next scheduled tick. Only the timer pokes.
 
-The footer widget shows `loop 5m · 3/25 · next 14:32`; `/loop status` shows the full card including the last tick's decision and reason.
+The footer status shows `loop 5m · 3/25 · next 14:32`, and a widget above the editor shows the same state with the loop focus beneath it; `/loop status` shows the full card including the last tick's decision and reason.
 
 ## Loop-aware compaction
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Interval wakeups for Pi: recurring prompt re-runs, stall rescue toward an active pi-goal goal, and loop-aware compaction that survives long sessions.",
   "type": "module",
   "keywords": [
@@ -38,6 +38,7 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   }
 }

package/src/index.ts

@@ -11,9 +11,13 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
 import { showLoopManager, showLoopSettings } from "./manager.js";
+import { registerLoopMessageRendering } from "./render.js";
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
+	// Collapse loop pokes into one-line transcript chips (display-only; the
+	// stored message and model context are untouched).
+	registerLoopMessageRendering(pi);
 
 	pi.registerCommand("loop", {
 		description:

package/src/loop.ts

@@ -43,6 +43,7 @@ import {
 	readPlanModeEnabled,
 	restoreLoopState,
 } from "./state.js";
+import { clearLoopWidget, updateLoopWidget } from "./widget.js";
 
 export const LOOP_STATUS_KEY = "loop";
 
@@ -100,6 +101,7 @@ export class LoopController {
 	onSessionShutdown(): void {
 		this.clearTimer();
 		this.wakePending = false;
+		if (this.sessionCtx) clearLoopWidget(this.sessionCtx.ui);
 		this.sessionCtx = undefined;
 	}
 
@@ -233,7 +235,7 @@ export class LoopController {
 		const loop = this.state;
 		if (!loop || !env.goal) return;
 		try {
-			this.pi.sendUserMessage(buildGoalPoke(loop, env.goal, reason));
+			this.pi.sendUserMessage(buildGoalPoke(loop, reason));
 		} catch (error) {
 			this.sessionCtx?.ui.notify(
 				`pi-loop could not deliver a wake: ${formatError(error)}. Retrying at the next interval.`,
@@ -319,6 +321,10 @@ export class LoopController {
 		const ui = this.sessionCtx?.ui;
 		if (!ui) return;
 		const loop = this.state;
+		updateLoopWidget(
+			ui,
+			loop ? { loop, wakePending: this.wakePending, nextWakeAt: this.nextWakeAt } : undefined,
+		);
 		if (!loop || loop.status === "stopped") {
 			ui.setStatus(LOOP_STATUS_KEY, undefined);
 			return;

package/src/messages.ts

@@ -15,22 +15,23 @@ function formatIteration(loop: LoopState): string {
 	return `${loop.iteration + 1}/${cap}`;
 }
 
-/** The goal-bound poke: restate the goal and wake goal_wait if applicable. */
-export function buildGoalPoke(
-	loop: LoopState,
-	goal: GoalSnapshot,
-	reason: "goal-stalled" | "goal-waiting",
-): string {
+/**
+ * The goal-bound poke: wake the session and point at the goal without
+ * restating it. Loops require an active pi-goal goal, so every poke turn
+ * already carries the objective, goal_id, and goal-mode rules through
+ * pi-goal's system prompt append; restating them here would store duplicate
+ * tokens in the conversation on every wake (see README: cross-extension
+ * assumption). Only the dynamic per-wake state (iteration, reason) belongs in
+ * this tail message.
+ */
+export function buildGoalPoke(loop: LoopState, reason: "goal-stalled" | "goal-waiting"): string {
 	const lines = [
 		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
 		reason === "goal-waiting"
 			? "This is the external wake for your waiting goal. Re-check whatever the goal was waiting on and continue."
-			: "The session went idle but the active goal is not complete. Continue working toward it.",
-		"",
-		`Active goal: ${goal.text}`,
+			: "The session went idle but the active goal is not complete. Continue working toward it — the objective and goal-mode rules are in the system prompt.",
 	];
 	if (loop.prompt) lines.push("", `Loop focus: ${loop.prompt}`);
-	lines.push("", "Use the goal tools (goal_complete, goal_blocked, goal_wait) when their conditions are met.");
 	return appendPokeMarker(lines.join("\n"), loop.id, loop.iteration + 1);
 }
 

package/src/render.ts

@@ -0,0 +1,33 @@
+/**
+ * Display-only compaction of loop-injected pokes.
+ *
+ * Pokes are already token-lean, but they still render as multi-line prompt
+ * text plus a provenance marker comment. This transformer collapses each into
+ * a one-line themed chip in the transcript. Display-only by Pi contract: the
+ * stored message and model context are untouched, and pokes keep being
+ * delivered through sendUserMessage so pi-goal's before_agent_start hook
+ * (which appends the goal system prompt) still fires for every poke turn.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { extractPokeMarker } from "./markers.js";
+
+const POKE_HEAD_PATTERN = /^Scheduled loop wakeup (\S+) \(every ([^)]+)\)\./u;
+const POKE_FOCUS_PATTERN = /^Loop focus: (.+)$/mu;
+
+export function registerLoopMessageRendering(pi: ExtensionAPI) {
+	pi.registerMarkdownTransformer((markdown, { messageType }) => {
+		if (messageType !== "user") return markdown;
+		return compactPokeMessage(markdown) ?? markdown;
+	});
+}
+
+/** Exported for tests: the poke chip, or undefined when not ours. */
+export function compactPokeMessage(markdown: string) {
+	if (!extractPokeMarker(markdown)) return undefined;
+	const head = POKE_HEAD_PATTERN.exec(markdown);
+	if (!head) return undefined;
+	const reason = markdown.includes("external wake") ? "waiting" : "stalled";
+	const focus = POKE_FOCUS_PATTERN.exec(markdown)?.[1];
+	return `*⏰ loop wake ${head[1]} · ${reason}${focus ? ` · ${focus}` : ""}*`;
+}

package/src/widget.ts

@@ -0,0 +1,81 @@
+/**
+ * The loop widget: a compact themed line above the editor mirroring the
+ * footer status (interval · iteration/cap · next wake), with the loop focus
+ * dimmed below it when set.
+ *
+ * Presentation only: every entry point tolerates a host without setWidget
+ * (test fixtures, print mode) and swallows render-side failures, because a
+ * widget must never interrupt loop state transitions.
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import { formatClock, formatDuration } from "./interval.js";
+import type { LoopState } from "./state.js";
+
+export const LOOP_WIDGET_KEY = "loop";
+
+interface WidgetTheme {
+	bold?: (text: string) => string;
+	fg?: (color: string, text: string) => string;
+}
+
+type WidgetHost = { setWidget?: unknown };
+
+export interface LoopWidgetView {
+	loop: LoopState;
+	/** A wake is held for the next idle boundary. */
+	wakePending: boolean;
+	/** Epoch ms of the next scheduled tick, when armed. */
+	nextWakeAt: number | undefined;
+}
+
+export function updateLoopWidget(ui: WidgetHost, view: LoopWidgetView | undefined) {
+	const setWidget = resolveSetWidget(ui);
+	if (!setWidget) return;
+	try {
+		if (!view || view.loop.status === "stopped") {
+			setWidget(LOOP_WIDGET_KEY, undefined);
+			return;
+		}
+		setWidget(LOOP_WIDGET_KEY, (_tui: unknown, theme: WidgetTheme) => {
+			const bold = theme.bold ?? identity;
+			const dim = (text: string) => theme.fg?.("dim", text) ?? text;
+			const focus = view.loop.prompt ? `\n${dim(`  focus: ${view.loop.prompt}`)}` : "";
+			return new Text(`${bold(loopWidgetLine(view))}${focus}`);
+		});
+	} catch {
+		// Presentation only; a widget failure must never break a loop transition.
+	}
+}
+
+export function clearLoopWidget(ui: WidgetHost) {
+	const setWidget = resolveSetWidget(ui);
+	if (!setWidget) return;
+	try {
+		setWidget(LOOP_WIDGET_KEY, undefined);
+	} catch {
+		// Presentation only.
+	}
+}
+
+export function loopWidgetLine(view: LoopWidgetView) {
+	const loop = view.loop;
+	if (loop.status === "paused") return "⏸ loop paused";
+	const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+	const next = view.wakePending
+		? "next on idle"
+		: view.nextWakeAt !== undefined
+			? `next ${formatClock(view.nextWakeAt)}`
+			: "next unscheduled";
+	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.iteration}/${cap} · ${next}`;
+}
+
+function identity(text: string) {
+	return text;
+}
+
+function resolveSetWidget(ui: WidgetHost) {
+	return typeof ui.setWidget === "function"
+		? (ui.setWidget as (key: string, content: unknown) => void).bind(ui)
+		: undefined;
+}