@matthewfl/pi-contemplator 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A Pi extension that keeps long-running agentic sessions on track with background memory, contemplation, and structural review.",
   "type": "module",
   "license": "MIT",

package/src/agents/contemplator/agent.ts

@@ -244,11 +244,24 @@ export class Contemplator {
 			}
 			this.persistReviewerStates(ctx);
 		});
+		this.pi.on("message_end", (event: any) => {
+			const message = event?.message;
+			if (message?.role !== "custom" || message.customType !== CONTEMPLATOR_SUGGESTION) return;
+			if (typeof message.details?.probeId !== "string") return;
+			// message_end means Pi has drained the steer into the conversation
+			// stream. It is no longer protected by an in-memory queue, so a later
+			// tree restore must be allowed to requeue it until context acknowledges it.
+			this.queuedProbeIds.delete(message.details.probeId);
+		});
 		this.pi.on("context", (event: any, ctx: ExtensionContext) => {
 			const deliveredMessages = event.messages?.filter((message: any) => message?.role === "custom" && message.customType === CONTEMPLATOR_SUGGESTION && typeof message.details?.probeId === "string") ?? [];
 			for (const delivered of deliveredMessages) {
 				if (this.deliveredProbeIds.has(delivered.details.probeId)) continue;
 				this.deliveredProbeIds.add(delivered.details.probeId);
+				// Once Pi includes the probe in a provider context it is no longer in
+				// either in-memory delivery queue. Keeping this id indefinitely caused
+				// later tree restores to suppress a genuinely needed requeue.
+				this.queuedProbeIds.delete(delivered.details.probeId);
 				this.pi.appendEntry(CONTEMPLATOR_SUGGESTION, {
 					version: 1,
 					suggestion: typeof delivered.details.question === "string" ? delivered.details.question : String(delivered.content ?? ""),
@@ -310,12 +323,7 @@ export class Contemplator {
 			this.turnsSinceRun = 0;
 		}
 		const undeliveredSuggestions = new Map<string, string>();
-		const queuedProbeIds = new Set<string>();
 		for (const entry of entries) {
-			if (entry.customType === CONTEMPLATOR_SUGGESTION && entry.type === "custom_message") {
-				const details = entry.details as { probeId?: unknown } | undefined;
-				if (typeof details?.probeId === "string") queuedProbeIds.add(details.probeId);
-			}
 			if (entry.customType === CONTEMPLATOR_STATE && entry.data && typeof entry.data === "object") {
 				const state = entry.data as { history?: unknown };
 				if (Array.isArray(state.history)) this.history = state.history.filter((message): message is AgentMessage => !!message && typeof message === "object");
@@ -380,7 +388,11 @@ export class Contemplator {
 		}
 		this.restoredTipId = tipId;
 		for (const [probeId, question] of undeliveredSuggestions) {
-			if (skipUndeliveredRestore || queuedProbeIds.has(probeId) || this.queuedProbeIds.has(probeId)) continue;
+			// A durable custom_message proves only that Pi inserted the probe at some
+			// point; it does not prove an in-memory queue still owns it, and compaction
+			// may have removed it from active model context. Suppress requeue only for
+			// ids this live extension instance still knows are queued.
+			if (skipUndeliveredRestore || this.queuedProbeIds.has(probeId)) continue;
 			this.queueProbe(ctx, question, "restore", probeId);
 		}
 		if (resetTracking) void this.resumePendingReviews(ctx);
@@ -650,18 +662,22 @@ export class Contemplator {
 
 	private queueProbe(ctx: MemoryUpdateCtx, question: string, source: "send_probe" | "restore", existingProbeId?: string): void {
 		const probeId = existingProbeId ?? `${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
+		// Persist intent before touching Pi's in-memory queue. A crash in between
+		// leaves a recoverable pending probe rather than an invisible lost one.
+		this.pi.appendEntry(CONTEMPLATOR_SUGGESTION, { version: 1, suggestion: question, delivered: false, source, probeId });
+		this.markTipPersisted(ctx);
+		// DELIVERY INVARIANT: probes must always use steer. The contemplator is
+		// designed for agents that run for hours; a probe must be injected after
+		// the current tool-call batch, before the very next model request. Never
+		// change this to nextTurn: that can postpone delivery until a user prompt.
+		// triggerTurn stays false so a probe never starts an extra agent turn.
+		if (this.agentActiveSince !== undefined) this.queuedProbeIds.add(probeId);
 		this.pi.sendMessage({
 			customType: CONTEMPLATOR_SUGGESTION,
 			content: `Background contemplator probe (advisory):\n${question}`,
 			display: this.runtime.config.showContemplatorMessages,
 			details: { version: 1, question, source, probeId },
 		}, { deliverAs: "steer", triggerTurn: false });
-		// sendMessage queues synchronously. Mark every source (not only restore)
-		// before a later turn_end can rebuild state from the still-undelivered
-		// tracking entry and enqueue this probe again.
-		this.queuedProbeIds.add(probeId);
-		this.pi.appendEntry(CONTEMPLATOR_SUGGESTION, { version: 1, suggestion: question, delivered: false, source, probeId });
-		this.markTipPersisted(ctx);
 		debugLog("contemplator.suggestion_queued", {
 			probeId,
 			suggestionLength: question.length,

package/src/hooks/compaction-resume.ts

@@ -30,13 +30,22 @@ function isCurrentWatch(runtime: Runtime, generation: number): boolean {
 	return runtime.compactionResumePending && runtime.compactionResumeGeneration === generation;
 }
 
-function sendResumeMessage(pi: ExtensionAPI, ctx: ResumeCtx, afterFailure: boolean): void {
+function continuationMessage(afterFailure: boolean, shortContinuationPrompt?: string): string {
+	if (shortContinuationPrompt) {
+		return afterFailure
+			? `Context compaction failed. Continue with these instructions:\n\n${shortContinuationPrompt}`
+			: shortContinuationPrompt;
+	}
+	return afterFailure
+		? "Context compaction failed. Continue the current task without waiting for another user message."
+		: "Continue the current task from the compacted context without waiting for another user message.";
+}
+
+function sendResumeMessage(pi: ExtensionAPI, ctx: ResumeCtx, afterFailure: boolean, shortContinuationPrompt?: string): void {
 	try {
 		pi.sendMessage({
 			customType: "om.compaction.resume",
-			content: afterFailure
-				? "Context compaction failed. Continue the current task without waiting for another user message."
-				: "Continue the current task from the compacted context without waiting for another user message.",
+			content: continuationMessage(afterFailure, shortContinuationPrompt),
 			display: false,
 		}, {
 			deliverAs: "followUp",
@@ -54,6 +63,7 @@ function scheduleResumeRetries(
 	ctx: ResumeCtx,
 	generation: number,
 	afterFailure: boolean,
+	shortContinuationPrompt: string | undefined,
 	retryIndex = 0,
 ): void {
 	if (!isCurrentWatch(runtime, generation)) return;
@@ -75,8 +85,8 @@ function scheduleResumeRetries(
 			`Observational memory: continuation did not start; retrying (${retryIndex + 1}/${RESUME_RETRY_DELAYS_MS.length})`,
 			"warning",
 		);
-		sendResumeMessage(pi, ctx, afterFailure);
-		scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure, retryIndex + 1);
+		sendResumeMessage(pi, ctx, afterFailure, shortContinuationPrompt);
+		scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure, shortContinuationPrompt, retryIndex + 1);
 	}, RESUME_RETRY_DELAYS_MS[retryIndex]);
 }
 
@@ -86,10 +96,11 @@ export function resumeAfterCompaction(
 	runtime: Runtime,
 	ctx: ResumeCtx,
 	afterFailure = false,
+	shortContinuationPrompt?: string,
 ): void {
 	const generation = beginResumeWatch(runtime);
-	sendResumeMessage(pi, ctx, afterFailure);
-	scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure);
+	sendResumeMessage(pi, ctx, afterFailure, shortContinuationPrompt);
+	scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure, shortContinuationPrompt);
 }
 
 /**
@@ -111,7 +122,7 @@ export function watchForNativeCompactionResume(
 			"warning",
 		);
 		sendResumeMessage(pi, ctx, false);
-		scheduleResumeRetries(pi, runtime, ctx, generation, false);
+		scheduleResumeRetries(pi, runtime, ctx, generation, false, undefined);
 	}, NATIVE_RESUME_GRACE_MS);
 }
 

package/src/hooks/compaction-trigger.ts

@@ -17,6 +17,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 		if (runtime.compactInFlight) return;
 
 		const agentRequested = runtime.compactRequested;
+		const shortContinuationPrompt = agentRequested ? runtime.compactContinuationPrompt : undefined;
 		if (agentRequested) runtime.compactRequested = false;
 		else if (runtime.config.passive === true) return;
 
@@ -88,6 +89,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 						"info",
 					);
 				}
+				if (agentRequested) runtime.compactContinuationPrompt = undefined;
 				ctx.compact({
 					onComplete: () => {
 						runtime.compactInFlight = false;
@@ -95,7 +97,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 						// Both explicit and proactive OM compactions are manual from Pi's
 						// perspective (willRetry=false), so Pi will not continue either one.
 						// Always enqueue a hidden continuation after OM finishes compacting.
-						resumeAfterCompaction(pi, runtime, { hasUI, ui });
+						resumeAfterCompaction(pi, runtime, { hasUI, ui }, false, shortContinuationPrompt);
 					},
 					onError: (error: { message: string }) => {
 						runtime.compactInFlight = false;
@@ -104,18 +106,19 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 						if (error.message !== "Compaction cancelled" && hasUI) {
 							ui?.notify(`Observational memory: ${error.message}`, "error");
 						}
-						resumeAfterCompaction(pi, runtime, { hasUI, ui }, true);
+						resumeAfterCompaction(pi, runtime, { hasUI, ui }, true, shortContinuationPrompt);
 					},
 				});
 			} catch (error) {
 				runtime.compactInFlight = false;
+				if (agentRequested) runtime.compactContinuationPrompt = undefined;
 				runtime.compactOrigin = undefined;
 				const msg = error instanceof Error ? error.message : String(error);
 				if (hasUI) {
 					ui?.setStatus?.(COMPACTION_STATUS_KEY, undefined);
 					ui?.notify(`Observational memory: compact threw: ${msg}`, "error");
 				}
-				resumeAfterCompaction(pi, runtime, { hasUI, ui }, true);
+				resumeAfterCompaction(pi, runtime, { hasUI, ui }, true, shortContinuationPrompt);
 			}
 		}, 0);
 	});

package/src/runtime.ts

@@ -145,6 +145,8 @@ export class Runtime {
 	consolidationPhase: ConsolidationPhase | undefined;
 	compactInFlight = false;
 	compactRequested = false;
+	/** Agent-authored instructions to deliver after an explicit compact_context request. */
+	compactContinuationPrompt: string | undefined;
 	compactOrigin: "proactive" | "agent-requested" | undefined;
 	compactHookInFlight = false;
 	compactionResumePending = false;
@@ -212,6 +214,7 @@ export class Runtime {
 		// never-cleared compactInFlight bricking all future compactions).
 		this.compactInFlight = false;
 		this.compactRequested = false;
+		this.compactContinuationPrompt = undefined;
 		this.compactOrigin = undefined;
 		this.compactionResumePending = false;
 		this.compactionResumeGeneration += 1;

package/src/tools/compact-context.ts

@@ -4,7 +4,7 @@ import type { Runtime } from "../runtime.js";
 
 export const COMPACT_CONTEXT_TOOL_NAME = "compact_context";
 export const COMPACT_CONTEXT_DESCRIPTION =
-	"Force manual compaction. Use sparingly when substantial work remains but the remaining context is insufficient, or when accumulated context has become noisy or stale enough to impair focus and reliable reasoning.";
+	"Force manual compaction and resume with agent-authored next-step instructions. Use sparingly when substantial work remains but the remaining context is insufficient, or when accumulated context has become noisy or stale enough to impair focus and reliable reasoning.";
 
 export type CompactContextDetails = {
 	status: "scheduled" | "already_pending" | "in_progress";
@@ -20,10 +20,17 @@ export function createCompactContextTool(runtime: Runtime) {
 		promptGuidelines: [
 			"Use compact_context sparingly when either substantial additional work remains and there is not enough context left to complete it, or accumulated past context has become noisy, stale, or distracting enough that you are struggling to focus on the current task or reason about it reliably.",
 			"Do not use compact_context routinely, for short tasks, or merely because the conversation is long; use it for genuine context-capacity pressure or context degradation that is interfering with the work.",
-			"Call compact_context by itself and stop the current turn; observational memory will compact the context and automatically resume the task.",
+			"Call compact_context by itself, provide short_continuation_prompt with concrete instructions for the next agent step, and stop the current turn; observational memory will compact the context and automatically resume with those instructions.",
 		],
-		parameters: Type.Object({}),
-		async execute() {
+		parameters: Type.Object({
+			short_continuation_prompt: Type.String({
+				minLength: 1,
+				maxLength: 1_000,
+				pattern: "\\S",
+				description: "Short, concrete instructions to your post-compaction self describing the next action and any critical immediate constraint. Do not summarize the whole conversation.",
+			}),
+		}),
+		async execute(_toolCallId, params) {
 			if (runtime.compactInFlight) {
 				return {
 					content: [{ type: "text" as const, text: "Context compaction is already in progress. Stop this turn and wait for automatic resume." }],
@@ -40,6 +47,7 @@ export function createCompactContextTool(runtime: Runtime) {
 			}
 
 			runtime.compactRequested = true;
+			runtime.compactContinuationPrompt = params.short_continuation_prompt.trim();
 			return {
 				content: [{ type: "text" as const, text: "Context compaction scheduled. Stop this turn; the task will resume automatically after compaction." }],
 				details: { status: "scheduled" } as CompactContextDetails,