@ryan_nookpi/pi-extension-subagent 0.5.10 → 0.5.12

package/index.ts

@@ -31,6 +31,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { SubagentAsyncTasks } from "./async-task-lifecycle.js";
 import { HANG_CHECK_INTERVAL_MS } from "./constants.js";
 import { SUBAGENT_COMMANDS, SUBAGENT_SHORTCUTS, type SubagentCommandName } from "./registration-manifest.js";
+import { handleRunningReminderContext, ReminderAnchors } from "./running-reminder.js";
 
 interface SubagentCore {
 	store: import("./store.js").SubagentStore;
@@ -120,9 +121,11 @@ export default function (pi: ExtensionAPI) {
 
 	let hangCheckTimer: ReturnType<typeof setInterval> | undefined;
 	let sessionGeneration = 0;
+	const reminderAnchors = new ReminderAnchors();
 
 	pi.on("session_start", (_event, ctx) => {
 		const generation = ++sessionGeneration;
+		reminderAnchors.clear();
 		const sessionId = ctx.sessionManager.getSessionId();
 		// Fence tool admission synchronously, before lazy lifecycle work can yield.
 		try {
@@ -148,6 +151,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_shutdown", async (event) => {
 		++sessionGeneration;
+		reminderAnchors.clear();
 		asyncTasks.shutdown();
 		if (hangCheckTimer) {
 			clearInterval(hangCheckTimer);
@@ -168,6 +172,21 @@ export default function (pi: ExtensionAPI) {
 		return c.commands.handleBeforeAgentStart(event, ctx, c.store);
 	});
 
+	// before_agent_start misses turns started by a delivered completion or a steer; context covers every
+	// LLM call, including the ones inside a tool loop. Reminders are pinned to the message they were first
+	// rendered after, so mid-turn requests keep them without moving the cached prefix.
+	// No core means no run was ever started, so there is nothing to wait for.
+	pi.on("context", (event, ctx) => {
+		if (!core || core.store.disposed) return;
+		let sessionFile: string | undefined;
+		try {
+			sessionFile = ctx.sessionManager.getSessionFile?.();
+		} catch {
+			sessionFile = undefined;
+		}
+		return handleRunningReminderContext(reminderAnchors, event.messages, core.store, sessionFile);
+	});
+
 	// If input arrives while the core is still loading, awaiting here lets the
 	// live handler-array dispatch reach the shortcut handlers registerAll adds.
 	pi.on("input", async () => {

package/lifecycle.ts

@@ -31,6 +31,13 @@ function reconcileRunWithPersistedSession(run: CommandRunState): void {
 		run.lastActivityAt = snapshot.latestActivityAt;
 	}
 	if (!snapshot.isTerminal) return;
+	// A live Pi child can still retry a persisted error. Only its runner's
+	// completion marker proves that failure recovery has finished.
+	if (
+		!snapshot.completionMarker &&
+		(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted")
+	)
+		return;
 
 	const exitCode =
 		snapshot.completionMarker?.exitCode ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,7 @@
     "retry.ts",
     "run-utils.ts",
     "runner.ts",
+    "running-reminder.ts",
     "session.ts",
     "starter-pack.ts",
     "store.ts",

package/runner.ts

@@ -762,6 +762,9 @@ async function runPiAgent(
 			let lastProcessSignal: NodeJS.Signals | null = null;
 			let lastEventAt = Date.now();
 			let sawAgentEnd = false;
+			// Covers both backoff and the resumed attempt, until Pi reports recovery
+			// or a final agent_end. Raw history can retain errors throughout this time.
+			let retryPending = false;
 			let settleReason = "unknown";
 			let unparsedStdoutCount = 0;
 			const unparsedStdoutTail: string[] = [];
@@ -813,10 +816,24 @@ async function runPiAgent(
 				}, 5000);
 			};
 
+			const clearCompletionFallbacks = () => {
+				if (agentEndFallbackTimer) clearTimeout(agentEndFallbackTimer);
+				if (terminalMessageFallbackTimer) clearTimeout(terminalMessageFallbackTimer);
+				agentEndFallbackTimer = undefined;
+				terminalMessageFallbackTimer = undefined;
+			};
+
 			const syncFromPersistedSession = (allowResolve: boolean): boolean => {
 				if (!sessionFile) return false;
 				const snapshot = readPersistedSessionSnapshot(sessionFile, { startOffset: persistedSessionBaseOffset });
-				if (snapshot.terminalStopReason && !currentResult.stopReason) {
+				const unconfirmedFailure =
+					!snapshot.completionMarker &&
+					(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted");
+				if (
+					snapshot.terminalStopReason &&
+					!currentResult.stopReason &&
+					(procExited || settled || (!retryPending && !unconfirmedFailure))
+				) {
 					currentResult.stopReason = snapshot.terminalStopReason;
 				}
 				if (snapshot.messages.length > currentResult.messages.length) {
@@ -824,7 +841,18 @@ async function runPiAgent(
 					currentResult.liveText = undefined;
 					emitUpdate();
 				}
-				if (!allowResolve || !snapshot.isTerminal || settled || procExited || wasAborted) return false;
+				// Persistence can beat stdout. An error response alone is not proof
+				// that Pi has finished: agent_end/auto_retry_start decide its recovery.
+				if (
+					!allowResolve ||
+					!snapshot.isTerminal ||
+					settled ||
+					procExited ||
+					wasAborted ||
+					retryPending ||
+					unconfirmedFailure
+				)
+					return false;
 
 				const forcedCode =
 					snapshot.completionMarker?.exitCode ??
@@ -855,15 +883,44 @@ async function runPiAgent(
 					return;
 				}
 				lastEventAt = Date.now();
+				// Once the local context guard settles the run, late shutdown events
+				// must not replace its failure with the child's last toolUse response.
+				if (contextGuardTripped) return;
+
+				if (event.type === "auto_retry_start") {
+					retryPending = true;
+					sawAgentEnd = false;
+					clearCompletionFallbacks();
+					return;
+				}
+
+				if (event.type === "auto_retry_end") {
+					retryPending = false;
+					if (event.success === false) {
+						currentResult.stopReason = "error";
+						if (event.finalError) currentResult.errorMessage = event.finalError;
+						sawAgentEnd = true;
+						writeCompletionMarkerOnce(1);
+						scheduleAgentEndForceResolve();
+					} else if (currentResult.stopReason === "error" || currentResult.stopReason === "aborted") {
+						// Successful recovery may arrive without its message_end on stdout.
+						// Wait for the successful agent_end instead of reusing the old error.
+						currentResult.stopReason = undefined;
+						currentResult.errorMessage = undefined;
+					} else if (currentResult.stopReason && currentResult.stopReason !== "toolUse") {
+						writeCompletionMarkerOnce(0);
+						scheduleTerminalMessageForceResolve();
+					}
+					return;
+				}
 
 				if (event.type === "agent_start" || event.type === "turn_start") {
 					sawAgentEnd = false;
+					currentResult.stopReason = undefined;
+					currentResult.errorMessage = undefined;
 					currentResult.liveThinking = undefined;
 					currentResult.thoughtText = undefined;
-					if (terminalMessageFallbackTimer) {
-						clearTimeout(terminalMessageFallbackTimer);
-						terminalMessageFallbackTimer = undefined;
-					}
+					clearCompletionFallbacks();
 					return;
 				}
 
@@ -873,21 +930,32 @@ async function runPiAgent(
 					// its objects are freshly deserialized, so reference-based deduplication
 					// would append every prior message again.
 					const eventMessages = (event.messages ?? []) as Message[];
-					const terminalMessage = [...eventMessages].reverse().find((msg) => Boolean((msg as any).stopReason));
+					const terminalMessage = [...eventMessages]
+						.reverse()
+						.find((msg) => msg.role === "assistant" && Boolean(msg.stopReason));
 					if (terminalMessage) {
 						const fingerprint = JSON.stringify(terminalMessage);
 						const alreadyCaptured = currentResult.messages.some((msg) => JSON.stringify(msg) === fingerprint);
 						if (!alreadyCaptured) currentResult.messages.push(terminalMessage);
-						if (!currentResult.stopReason) {
-							currentResult.stopReason = (terminalMessage as any).stopReason;
-							if ((terminalMessage as any).errorMessage) {
-								currentResult.errorMessage = (terminalMessage as any).errorMessage;
-							}
-						}
+						currentResult.stopReason = (terminalMessage as any).stopReason;
+						currentResult.errorMessage = (terminalMessage as any).errorMessage;
 					} else if (currentResult.messages.length === 0 && eventMessages.length > 0) {
 						currentResult.messages.push(eventMessages[eventMessages.length - 1]);
 					}
-					if (currentResult.stopReason && currentResult.stopReason !== "toolUse") {
+					if (event.willRetry === true) {
+						retryPending = true;
+						sawAgentEnd = false;
+						clearCompletionFallbacks();
+						return;
+					}
+					retryPending = false;
+					if (
+						currentResult.stopReason &&
+						currentResult.stopReason !== "toolUse" &&
+						// Older Pi versions omit willRetry; defer their failure marker
+						// until fallback so auto_retry_start can still cancel completion.
+						(currentResult.stopReason !== "error" || event.willRetry === false)
+					) {
 						writeCompletionMarkerOnce(
 							currentResult.stopReason === "error" || currentResult.stopReason === "aborted" ? 1 : 0,
 						);
@@ -977,7 +1045,7 @@ async function runPiAgent(
 						}
 						if (!currentResult.model && msg.model) currentResult.model = msg.model;
 						if (msg.stopReason) currentResult.stopReason = msg.stopReason;
-						if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
+						currentResult.errorMessage = msg.errorMessage;
 						currentResult.liveThinking = undefined;
 
 						// Extract thoughtText from thinking block first line only
@@ -989,8 +1057,15 @@ async function runPiAgent(
 							}
 						}
 						const terminalStopReason = (msg as any).stopReason;
-						if (terminalStopReason && terminalStopReason !== "toolUse") {
-							writeCompletionMarkerOnce(terminalStopReason === "error" || terminalStopReason === "aborted" ? 1 : 0);
+						// Error message_end precedes Pi's retry decision. Do not publish
+						// completion or arm a timeout while it may still recover.
+						if (
+							terminalStopReason &&
+							terminalStopReason !== "toolUse" &&
+							terminalStopReason !== "error" &&
+							!retryPending
+						) {
+							writeCompletionMarkerOnce(terminalStopReason === "aborted" ? 1 : 0);
 							scheduleTerminalMessageForceResolve();
 						}
 					}
@@ -1062,11 +1137,18 @@ async function runPiAgent(
 			};
 
 			function scheduleTerminalMessageForceResolve() {
-				if (!currentResult.stopReason || currentResult.stopReason === "toolUse" || settled || procExited) return;
+				if (
+					!currentResult.stopReason ||
+					currentResult.stopReason === "toolUse" ||
+					retryPending ||
+					settled ||
+					procExited
+				)
+					return;
 				if (terminalMessageFallbackTimer) clearTimeout(terminalMessageFallbackTimer);
 
 				terminalMessageFallbackTimer = setTimeout(() => {
-					if (settled || procExited || wasAborted) return;
+					if (settled || procExited || wasAborted || retryPending) return;
 
 					const forcedCode = currentResult.stopReason === "error" || currentResult.stopReason === "aborted" ? 1 : 0;
 
@@ -1082,12 +1164,12 @@ async function runPiAgent(
 			// (e.g. lingering extension timers/transports). In that case, force
 			// resolve after a short quiet period so runs do not remain "running" forever.
 			function scheduleAgentEndForceResolve() {
-				if (!sawAgentEnd || settled || procExited) return;
+				if (!sawAgentEnd || retryPending || settled || procExited) return;
 				if (agentEndFallbackTimer) clearTimeout(agentEndFallbackTimer);
 
 				const marker = lastEventAt;
 				agentEndFallbackTimer = setTimeout(() => {
-					if (settled || procExited || wasAborted) return;
+					if (settled || procExited || wasAborted || retryPending) return;
 					if (lastEventAt !== marker) return;
 
 					const forcedCode = currentResult.stopReason === "error" || currentResult.stopReason === "aborted" ? 1 : 0;

package/running-reminder.ts

@@ -0,0 +1,207 @@
+/**
+ * Per-request reminder of subagent runs whose results have not reached the model yet.
+ *
+ * Imports nothing beyond the leaf time-utils module so index.ts can register the context handler
+ * without loading the core.
+ */
+
+import type { SubagentStore } from "./store.js";
+import type { CommandRunState } from "./types.js";
+import { formatElapsedSince } from "./utils/time-utils.js";
+
+export const RUNNING_REMINDER_CUSTOM_TYPE = "subagent-running-reminder";
+const MAX_REMINDER_TASK_LENGTH = 60;
+/** Enough to cover a long turn; the oldest anchors fall off a session that runs agents for hours. */
+const MAX_ANCHORS = 50;
+/** A hosted runtime can serve a few sessions from one extension instance. */
+const MAX_ANCHOR_SCOPES = 4;
+
+type ReminderStore = Pick<SubagentStore, "globalLiveRuns" | "batchGroups" | "pipelines">;
+
+function normalizeSessionFile(value: string | undefined | null): string {
+	return typeof value === "string" ? value.replace(/[\r\n\t]+/g, "").trim() : "";
+}
+
+function shortTask(run: CommandRunState): string {
+	const raw = (run.displayTask || run.task || "").replace(/\s+/g, " ").trim().replaceAll('"', "'");
+	return raw.length > MAX_REMINDER_TASK_LENGTH ? `${raw.slice(0, MAX_REMINDER_TASK_LENGTH - 3)}...` : raw;
+}
+
+/**
+ * Runs started from this session whose completion still goes to the model. Ownership matches
+ * tool-execute's origin check: an unknown session file on either side counts as the same session.
+ *
+ * A finished run stays listed only while someone still owes its delivery: its own held completion, or
+ * the batch or pipeline summary it belongs to. Entries whose group was already evicted are orphans and
+ * must not keep the model quiet forever.
+ */
+export function collectPendingRuns(store: ReminderStore, currentSessionFile: string | undefined): CommandRunState[] {
+	const current = normalizeSessionFile(currentSessionFile);
+	const runs: CommandRunState[] = [];
+	for (const entry of store.globalLiveRuns.values()) {
+		const run = entry.runState;
+		if (run.removed || run.deliveryMode === "humanOnly") continue;
+		if (run.status !== "running" && !deliveryStillOwed(store, entry.pendingCompletion !== undefined, run)) continue;
+		const origin = normalizeSessionFile(entry.originSessionFile);
+		if (current && origin && current !== origin) continue;
+		runs.push(run);
+	}
+	return runs.sort((left, right) => left.startedAt - right.startedAt || left.id - right.id);
+}
+
+function deliveryStillOwed(store: ReminderStore, hasPendingCompletion: boolean, run: CommandRunState): boolean {
+	if (hasPendingCompletion) return true;
+	if (run.batchId && store.batchGroups.has(run.batchId)) return true;
+	return Boolean(run.pipelineId && store.pipelines.has(run.pipelineId));
+}
+
+export function formatRunningReminder(runs: readonly CommandRunState[], now: number): string | undefined {
+	if (runs.length === 0) return undefined;
+	const items = runs.map((run) => {
+		const task = shortTask(run);
+		const head = `subagent run #${run.id} ${run.agent}${task ? ` "${task}"` : ""}`;
+		if (run.status !== "running") return `${head} finished, result not delivered yet`;
+		return `${head} ${formatElapsedSince(run.startedAt, now)}`;
+	});
+	return `Still running or awaiting delivery (results NOT delivered yet): ${items.join("; ")}. Do not state their final outcome, counts, hashes, or artifacts until their completion notification arrives or you read their final status yourself; partial output you read via the tool may be described as in-progress.`;
+}
+
+interface Anchor {
+	/** Frozen when the anchor is created, so later requests repeat it byte for byte. */
+	text: string;
+	timestamp: number;
+}
+
+interface AnchorScope {
+	anchors: Map<string, Anchor>;
+	/** Ids the most recently created anchor already names, so a shrinking set does not add anchors. */
+	covered: ReadonlySet<string>;
+}
+
+/**
+ * Pi clones the messages for every request, so an anchor cannot hold a message reference. Role,
+ * timestamp, and the id of a tool result or custom message identify the same message across requests.
+ */
+function anchorKey(message: unknown): string | undefined {
+	const candidate = message as
+		| { role?: unknown; timestamp?: unknown; toolCallId?: unknown; customType?: unknown }
+		| undefined;
+	if (!candidate || typeof candidate.role !== "string" || typeof candidate.timestamp !== "number") return undefined;
+	const detail =
+		typeof candidate.toolCallId === "string"
+			? candidate.toolCallId
+			: typeof candidate.customType === "string"
+				? candidate.customType
+				: "";
+	return `${candidate.role}|${candidate.timestamp}|${detail}`;
+}
+
+/**
+ * Keeps the reminder visible inside a tool loop without breaking the prompt cache.
+ *
+ * Appending a freshly rendered reminder to every request would change the tail each time and invalidate
+ * the cached prefix. Instead each reminder is pinned to the message it was first rendered after and
+ * replayed there verbatim, so a request built later in the same turn only grows at the end.
+ */
+export class ReminderAnchors {
+	/** Keyed by session file: a hosted runtime can route another session's request through this instance. */
+	private readonly scopes = new Map<string, AnchorScope>();
+
+	clear(): void {
+		this.scopes.clear();
+	}
+
+	isEmpty(): boolean {
+		for (const scope of this.scopes.values()) if (scope.anchors.size > 0) return false;
+		return true;
+	}
+
+	apply<T>(
+		session: string,
+		messages: readonly T[],
+		pending: { ids: readonly string[]; render: () => string | undefined },
+		now: number,
+	): { messages: T[] } | undefined {
+		const known = this.scopes.get(session);
+		if (pending.ids.length === 0 && !known?.anchors.size) return undefined;
+		const scope = known ?? this.openScope(session);
+		recordAnchor(scope, messages, pending, now);
+		if (scope.anchors.size === 0) return undefined;
+		return insertAnchors(scope.anchors, messages);
+	}
+
+	private openScope(session: string): AnchorScope {
+		const scope: AnchorScope = { anchors: new Map(), covered: new Set() };
+		this.scopes.set(session, scope);
+		while (this.scopes.size > MAX_ANCHOR_SCOPES) {
+			const oldest = this.scopes.keys().next().value;
+			if (oldest === undefined) break;
+			this.scopes.delete(oldest);
+		}
+		return scope;
+	}
+}
+
+function recordAnchor<T>(
+	scope: AnchorScope,
+	messages: readonly T[],
+	pending: { ids: readonly string[]; render: () => string | undefined },
+	now: number,
+): void {
+	if (pending.ids.length === 0) return;
+	const last = messages.at(-1);
+	const key = anchorKey(last);
+	if (!key) return;
+	const continuesTurn = (last as { role?: unknown } | undefined)?.role === "toolResult";
+	// Mid-turn requests only earn an anchor once work the model has not been warned about shows up.
+	if (continuesTurn && pending.ids.every((id) => scope.covered.has(id))) return;
+	const text = pending.render();
+	if (!text) return;
+	scope.anchors.set(key, { text, timestamp: now });
+	scope.covered = new Set(pending.ids);
+	while (scope.anchors.size > MAX_ANCHORS) {
+		const oldest = scope.anchors.keys().next().value;
+		if (oldest === undefined) break;
+		scope.anchors.delete(oldest);
+	}
+}
+
+function insertAnchors<T>(anchors: ReadonlyMap<string, Anchor>, messages: readonly T[]): { messages: T[] } | undefined {
+	const result: T[] = [];
+	let inserted = false;
+	for (const message of messages) {
+		result.push(message);
+		const key = anchorKey(message);
+		const anchor = key ? anchors.get(key) : undefined;
+		if (!anchor) continue;
+		result.push({
+			role: "custom",
+			customType: RUNNING_REMINDER_CUSTOM_TYPE,
+			content: anchor.text,
+			display: false,
+			timestamp: anchor.timestamp,
+		} as unknown as T);
+		inserted = true;
+	}
+	return inserted ? { messages: result } : undefined;
+}
+
+/**
+ * context handler body. Pi fires context before every LLM call, and does not persist the returned
+ * messages, so the reminder never enters the transcript.
+ */
+export function handleRunningReminderContext<T>(
+	anchors: ReminderAnchors,
+	messages: readonly T[],
+	store: ReminderStore | null | undefined,
+	currentSessionFile: string | undefined,
+	now = Date.now(),
+): { messages: T[] } | undefined {
+	const runs = store ? collectPendingRuns(store, currentSessionFile) : [];
+	return anchors.apply(
+		normalizeSessionFile(currentSessionFile),
+		messages,
+		{ ids: runs.map((run) => String(run.id)), render: () => formatRunningReminder(runs, now) },
+		now,
+	);
+}