@hank-warren/pi-loop 0.8.0 → 1.0.0

package/src/loop.ts

@@ -71,6 +71,8 @@ import {
 	readPlanModeEnabled,
 	restoreLoopState,
 } from "./state.js";
+import { publishLoopEnv } from "./loop-env.js";
+import { showLoopProposalCard } from "./presentation.js";
 import { isLoopOkAck } from "./ack.js";
 import { calledTool, hasAssistantToolCall, nextNoProgressState } from "./safety.js";
 import { classifyInterruption } from "./errors.js";
@@ -87,6 +89,8 @@ import {
 	buildProposal,
 	type LoopPlanningState,
 	type LoopProposal,
+	type LoopProposalOverrides,
+	normalizeGroundRules,
 } from "./planning.js";
 import {
 	clearLoopWidget,
@@ -128,13 +132,27 @@ type RunOrigin = "continuation" | "fallback";
  * The outcome of a start attempt.
  *
  * `startLoop` used to report its refusals by calling `ctx.ui.notify` itself,
- * which tied the only start path to a UI. Two callers now share that path —
- * the `/loop` command and the `loop_start` tool — and the tool has to turn
- * the same refusal into tool content rather than a toast, so the decision is
- * returned and each caller renders it.
+ * which tied the only start path to a UI. The approval card's two start
+ * actions share that path — one installs the loop here, the other hands it to
+ * a fresh session — so the decision is returned and each caller renders it.
  */
 export type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
 
+/**
+ * A loop that exists but is not running anywhere: everything `installLoop`
+ * needs, and nothing that presumes which session will install it.
+ */
+export interface BuiltLoop {
+	loop: LoopState;
+	/** The criteria to write at install: proposed, or the deterministic split. */
+	criteria: LoopCriterion[];
+	expiryMs: number;
+	clamped: boolean;
+	requestedMs: number;
+}
+
+export type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
+
 interface ContinuationIntent {
 	loopId: string;
 	kind: ContinuationKind;
@@ -240,6 +258,10 @@ export class LoopController {
 		this.ledger = undefined;
 		this.ledgerWarned = false;
 		this.state = restoreLoopState(ctx.sessionManager.getBranch());
+		// A restored loop is running from this moment, so the signal other
+		// extensions read has to be true again before the first tool call of the
+		// session, not only after the first state change.
+		publishLoopEnv(this.state);
 		if (this.state && this.state.status === "active") {
 			if (this.now() >= this.state.expiresAt) {
 				this.transition("stopped", "loop expired while the session was away");
@@ -252,11 +274,37 @@ export class LoopController {
 			// A wait whose deadline passed while the session was away is due now.
 			this.restoreWaitTimer();
 			this.armFallback();
+			// A loop handed over from another session has never had its first turn.
+			if (this.state.handoff) this.consumeHandoff(ctx);
 		}
 		this.updateWidget();
 	}
 
+	/**
+	 * Take delivery of a loop handed to this session, and start working it.
+	 *
+	 * The flag is cleared first and persisted immediately: a handoff is
+	 * consumed exactly once, and a session that crashed between restoring and
+	 * kicking off must not re-anchor the objective on the next start.
+	 */
+	private consumeHandoff(ctx: ExtensionContext): void {
+		const loop = this.state;
+		if (!loop) return;
+		const { handoff: _handoff, ...rest } = loop;
+		this.state = rest;
+		this.persist();
+		ctx.ui.notify(
+			"Loop started in this session: only the objective crossed over, not the planning conversation. It works from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you stop it from the /loop menu.",
+			"info",
+		);
+		this.sendKickoffAnchor(ctx);
+		this.requestContinuation(rest, "kickoff");
+		this.dispatchContinuationIfSettled(ctx);
+	}
+
 	onSessionShutdown(): void {
+		// Withdraw the signal: the process may outlive this session.
+		publishLoopEnv(undefined);
 		this.clearTimer();
 		this.waitTimer.clear();
 		this.wakePending = false;
@@ -324,14 +372,14 @@ export class LoopController {
 			case "usage-limited":
 				this.transition(
 					"paused",
-					"the provider reports the usage limit is reached; resume with /loop resume once it resets",
+					"the provider reports the usage limit is reached; resume it from the /loop menu once it resets",
 					"usage limit reached",
 				);
 				return true;
 			case "fatal":
 				this.transition(
 					"paused",
-					"the turn failed with an error a retry cannot fix; resolve it, then /loop resume",
+					"the turn failed with an error a retry cannot fix; resolve it, then resume it from the /loop menu",
 					"unrecoverable provider error",
 				);
 				return true;
@@ -339,7 +387,7 @@ export class LoopController {
 				// Esc, or another extension stopping the turn. A loop-caused run
 				// that the user interrupted must not be immediately re-sent.
 				if (origin === undefined) return false;
-				this.transition("paused", "the turn was interrupted; resume with /loop resume", "interrupted");
+				this.transition("paused", "the turn was interrupted; resume it from the /loop menu", "interrupted");
 				return true;
 			case "context-overflow":
 				// The request no longer fits: compact first, then continue. The
@@ -361,7 +409,7 @@ export class LoopController {
 	 * The no-progress breaker: consecutive tool-free loop turns with identical
 	 * visible output pause the loop instead of waking it again forever. It
 	 * pauses rather than stops, so the loop stays configured and one
-	 * `/loop resume` (or the next user prompt) puts it back to work.
+	 * Resuming from the /loop menu (or the next user prompt) puts it back to work.
 	 */
 	private enforceNoProgress(
 		ctx: ExtensionContext,
@@ -404,7 +452,7 @@ export class LoopController {
 		void ctx;
 		this.transition(
 			"paused",
-			`${next.toolFreeRepeatCount} loop turns in a row produced the same answer and called no tools; the loop is still configured, so /loop resume (or your next message) continues it`,
+			`${next.toolFreeRepeatCount} loop turns in a row produced the same answer and called no tools; the loop is still configured, so resuming from the /loop menu (or your next message) continues it`,
 			"no progress",
 		);
 		return true;
@@ -487,7 +535,7 @@ export class LoopController {
 		if (!objective) {
 			this.transition(
 				"paused",
-				"it was bound to a goal that is gone and has no objective of its own; start a new loop with /loop <interval> <objective>",
+				"it was bound to a goal that is gone and has no objective of its own; run /loop to plan and approve a new one",
 				"loop with no objective",
 			);
 			return true;
@@ -517,7 +565,7 @@ export class LoopController {
 		if (this.completeToolAvailable()) return false;
 		this.transition(
 			"paused",
-			`the ${LOOP_COMPLETE_TOOL} tool is not available in this session, so the loop could never end itself; re-enable it, then /loop resume`,
+			`the ${LOOP_COMPLETE_TOOL} tool is not available in this session, so the loop could never end itself; re-enable it, then resume the loop from the /loop menu`,
 			"loop_complete unavailable",
 		);
 		void ctx;
@@ -551,7 +599,7 @@ export class LoopController {
 		if (this.deadDeliveries < MAX_DEAD_DELIVERIES) return false;
 		this.transition(
 			"paused",
-			`${this.deadDeliveries} loop messages in a row produced no turn at all, so something is refusing every request; fix it, then /loop resume`,
+			`${this.deadDeliveries} loop messages in a row produced no turn at all, so something is refusing every request; fix it, then resume the loop from the /loop menu`,
 			"deliveries produce no turns",
 		);
 		return true;
@@ -632,7 +680,7 @@ export class LoopController {
 	 * no writable ledger still runs, it just loses the durable record, so the
 	 * failure is warned once and never repeated.
 	 *
-	 * `criteria` is passed at start: the criteria proposed at `loop_start`, or
+	 * `criteria` is passed at start: the criteria approved with the draft, or
 	 * the deterministic split of the objective. On restore it is omitted, and
 	 * the criteria already on disk are authoritative — they are the ones the
 	 * user saw echoed, and re-deriving them would both discard a proposed set
@@ -660,6 +708,20 @@ export class LoopController {
 		this.ledger = paths;
 	}
 
+	/**
+	 * Write a built loop's ledger without installing the loop.
+	 *
+	 * The fresh-session launch needs the approved criteria on disk *before* the
+	 * new session restores the state, because the restore path treats an
+	 * existing `criteria.json` as authoritative and would otherwise re-derive
+	 * its own. Returns a failure detail, or undefined on success.
+	 */
+	prepareLedgerFor(built: BuiltLoop): string | undefined {
+		const objective = built.loop.objective;
+		if (objective === undefined) return "the loop has no objective";
+		return createLedger(ledgerPaths(built.loop.id, this.agentDir), objective, built.criteria);
+	}
+
 	/** The loop's criteria as last written to disk, fail-open. */
 	criteria() {
 		return this.ledger ? readCriteria(this.ledger) : undefined;
@@ -756,7 +818,7 @@ export class LoopController {
 			// Nothing is scheduled once the timer has fired. `runTick` re-arms it
 			// through `scheduleTick` when it pokes, but a busy or compacting
 			// session coalesces into `wakePending` instead — and leaving the old
-			// deadline here made `/loop status` report a clock time that had
+			// deadline here made the /loop status screen report a clock time that had
 			// already passed.
 			this.nextWakeAt = undefined;
 			const ctx = this.sessionCtx;
@@ -1000,6 +1062,9 @@ export class LoopController {
 
 	persist(): void {
 		if (!this.state) return;
+		// Every state change funnels through here, which makes it the one place
+		// the loop-active signal can be published without a caller remembering to.
+		publishLoopEnv(this.state);
 		this.pi.appendEntry(LOOP_STATE_ENTRY_TYPE, { loop: this.state });
 	}
 
@@ -1064,7 +1129,7 @@ export class LoopController {
 
 	statusLines(ctx: ExtensionContext): string[] {
 		const loop = this.state;
-		if (!loop) return ["No loop in this session. Start one with /loop <interval> [prompt]."];
+		if (!loop) return ["No loop in this session. Run /loop to plan one."];
 		const lines = [
 			`Status: ${loop.status}${loop.pauseCause ? ` (${loop.pauseCause})` : ""}`,
 			...(loop.waiting
@@ -1144,10 +1209,7 @@ export class LoopController {
 	}
 
 	/** Record a drafted loop for approval, replacing any previous draft. */
-	propose(
-		objective: string,
-		overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
-	): LoopProposal {
+	propose(objective: string, overrides: LoopProposalOverrides = {}): LoopProposal {
 		const proposal = buildProposal(
 			objective,
 			{
@@ -1158,11 +1220,29 @@ export class LoopController {
 			this.now(),
 			overrides,
 		);
+		// A new draft supersedes the last one, so the card that was shown for the
+		// old draft no longer describes what would start.
 		this.planning = { active: true, proposal };
 		this.updateWidget();
 		return proposal;
 	}
 
+	/**
+	 * Render the current draft's approval card, at most once per draft.
+	 *
+	 * Called by `loop_propose` when the draft is created and by `/loop` when the
+	 * user reopens the actions, so the card is present whichever way they got
+	 * here without a second copy appearing when they got here both ways.
+	 */
+	showProposalCard(ctx: ExtensionContext): boolean {
+		const proposal = this.planning.proposal;
+		if (!proposal) return false;
+		if (this.planning.cardShownAt === proposal.proposedAt) return false;
+		if (!showLoopProposalCard(this.pi, ctx, proposal)) return false;
+		this.planning = { ...this.planning, cardShownAt: proposal.proposedAt };
+		return true;
+	}
+
 	endPlanning(): void {
 		this.planning = { active: false };
 		this.updateWidget();
@@ -1174,16 +1254,38 @@ export class LoopController {
 	 * Start a loop on its own objective, the only mode there is: the trailing
 	 * text *is* what the loop works on and what `loop_complete` answers for.
 	 * With no text there is nothing to work on, and the caller is told so.
+	 *
+	 * Build and install are separate below, and this is the two of them in the
+	 * order they have always run. The split exists because "construct a loop"
+	 * and "make this session the one running it" were one indivisible pass, and
+	 * a fresh-session launch needs the first without the second: the state has
+	 * to exist before `ctx.newSession` so its `setup` can append it to the new
+	 * session, and it must not be installed here or the launching session would
+	 * start working the objective it is handing away.
 	 */
 	startLoop(ctx: ExtensionContext, start: LoopStartArguments): LoopStartResult {
 		this.sessionCtx = ctx;
+		const built = this.buildLoop(start);
+		if (!built.ok) return built;
+		return this.installLoop(ctx, built.built);
+	}
+
+	/**
+	 * Construct a loop's state and criteria without installing anything.
+	 *
+	 * Pure with respect to the session: no `this.state`, no ledger on disk, no
+	 * timer, no widget, no message. Everything it reads (settings, the clock,
+	 * the tool set) is read-only, so a caller may build a loop it intends to
+	 * install somewhere else — or discard.
+	 */
+	buildLoop(start: LoopStartArguments): LoopBuildResult {
 		const now = this.now();
 		const objective = start.prompt?.trim();
 		if (!objective) {
 			return {
 				ok: false,
 				message:
-					"A loop needs something to work on. Give it an objective: /loop <interval> <objective with completion criteria>.",
+					"A loop needs something to work on. Run /loop and draft an objective with completion criteria first.",
 			};
 		}
 		// A loop with no way to call loop_complete would work, finish, and then be
@@ -1203,10 +1305,12 @@ export class LoopController {
 				: this.settings.compaction.enabled
 					? this.settings.compaction.threshold
 					: null;
-		const started: LoopState = {
+		const groundRules = normalizeGroundRules(start.groundRules);
+		const loop: LoopState = {
 			id: randomUUID().slice(0, 8),
 			status: "active",
 			objective,
+			...(groundRules ? { groundRules } : {}),
 			intervalMs: start.intervalMs,
 			maxTurns: start.maxTurns !== undefined ? start.maxTurns : this.settings.maxTurns,
 			compactAt,
@@ -1215,23 +1319,44 @@ export class LoopController {
 			startedAt: now,
 			expiresAt: now + expiryMs,
 		};
+		return {
+			ok: true,
+			built: {
+				loop,
+				criteria: start.criteria
+					? criteriaFromDescriptions(start.criteria)
+					: deriveCriteria(objective),
+				expiryMs,
+				clamped: start.clamped,
+				requestedMs: start.requestedMs,
+			},
+		};
+	}
+
+	/**
+	 * Install a built loop into `ctx`'s session: adopt it as the live state,
+	 * open its ledger, persist, arm the fallback, anchor the objective and kick
+	 * off the first turn. This is the half that makes a session *the* session
+	 * running the loop, and it is the half a fresh-session launch runs over
+	 * there rather than here.
+	 */
+	installLoop(ctx: ExtensionContext, built: BuiltLoop): LoopStartResult {
+		this.sessionCtx = ctx;
+		const started = built.loop;
 		this.state = started;
 		this.wakePending = false;
 		this.continuationIntent = undefined;
 		this.noOpStreak = 0;
 		this.ledgerWarned = false;
-		this.openLedger(
-			this.state,
-			start.criteria ? criteriaFromDescriptions(start.criteria) : deriveCriteria(objective),
-		);
+		this.openLedger(started, built.criteria);
 		this.persist();
-		this.scheduleTick(start.intervalMs);
+		this.scheduleTick(started.intervalMs);
 		this.updateWidget();
-		const clampNote = start.clamped
-			? ` (requested ${formatDuration(start.requestedMs)}, clamped to the ${formatDuration(start.intervalMs)} minimum)`
+		const clampNote = built.clamped
+			? ` (requested ${formatDuration(built.requestedMs)}, clamped to the ${formatDuration(started.intervalMs)} minimum)`
 			: "";
 		ctx.ui.notify(
-			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop. Fallback wake every ${formatDuration(start.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(expiryMs)} (one final turn to write its state down, then it stops).`,
+			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you stop it from the /loop menu. Fallback wake every ${formatDuration(started.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(built.expiryMs)} (one final turn to write its state down, then it stops).`,
 			"info",
 		);
 		if (this.ledger) {
@@ -1256,6 +1381,8 @@ export class LoopController {
 		return { ok: true, loop: started };
 	}
 
+
+
 	/**
 	 * Store the objective as an ordinary message so it outlives the loop.
 	 *