@matthewfl/pi-contemplator 0.0.2 → 0.0.4

package/README.md

@@ -96,7 +96,7 @@ pi -e ./src/index.ts
 
 ## Configuration and commands
 
-The plugin works with its defaults, including the contemplator and reviewer. Model selection, trigger thresholds, passive mode, compaction behavior, and other settings are documented in [docs/configuration.md](docs/configuration.md).
+The plugin works with its defaults, including the contemplator and reviewer. Contemplator probes and review notices appear as purple cards in the chat by default; use `/om:settings messages off` to hide newly sent cards without stopping their delivery to the agent. Model selection, trigger thresholds, passive mode, compaction behavior, and other settings are documented in [docs/configuration.md](docs/configuration.md).
 
 Useful commands include:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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

@@ -4,6 +4,7 @@ import type { Static } from "typebox";
 import { streamSimple } from "@earendil-works/pi-ai/compat";
 import { generateSummaryWithUsage } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
 import { assistantOutputTokens, assistantToolCallCount, fullProjection, isReviewRequestEntry, isReviewResultEntry, OM_REVIEWER_MESSAGE, OM_REVIEWER_NOTICE, OM_REVIEWER_STATE, OM_REVIEW_REQUEST, OM_REVIEW_RESULT, type Entry, type ReviewResult, type StructuralReviewRequest } from "../../session-ledger/index.js";
 import { hashId } from "../../ids.js";
 import { createSearchMemoriesAgentTool } from "../../tools/search-memories.js";
@@ -80,9 +81,19 @@ function reviewSummaryLine(review: ReviewResult): string {
 function reviewRequestKey(request: RequestReviewArgs): string {
 	return `${request.scope}:${hashId(`${request.evidence}\n${request.concern}`)}`;
 }
+
+function customMessageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => block && typeof block === "object" && "text" in block && typeof block.text === "string" ? block.text : "")
+		.filter(Boolean)
+		.join("\n");
+}
 const CONTEMPLATOR_MESSAGE = "om.contemplator.message";
 const CONTEMPLATOR_STATE = "om.contemplator.state";
 const CONTEMPLATOR_SUGGESTION = "om.contemplator.suggestion";
+const REVIEW_PROPOSAL_MESSAGE = "om.review.proposal";
 const SendProbeSchema = Type.Object({ question: Type.String({ minLength: 1, description: "One concise, memory-grounded probing question, optionally preceded by one short sentence of context. Cite relevant memory identifiers." }) });
 const ReviewScopeSchema = Type.Union([Type.Literal("workflow"), Type.Literal("software")]);
 export const RequestReviewSchema = Type.Object({
@@ -143,7 +154,8 @@ export class Contemplator {
 	private resumedReviewIds = new Set<string>();
 	private reviewerSessions = new Map<string, ReviewerSession>();
 	private deliveredProbeIds = new Set<string>();
-	private requeuedProbeIds = new Set<string>();
+	/** Probe ids passed to pi.sendMessage by this live extension runtime. */
+	private queuedProbeIds = new Set<string>();
 	private sessionGeneration = 0;
 	private latestCtx: MemoryUpdateCtx | undefined;
 	private turnsSinceRun = 0;
@@ -152,13 +164,31 @@ export class Contemplator {
 	constructor(private readonly pi: ExtensionAPI, private readonly runtime: Runtime) {}
 
 	register(): void {
+		this.pi.registerMessageRenderer(CONTEMPLATOR_SUGGESTION, (message, _options, theme) => {
+			const content = customMessageText(message.content).replace(/^Background contemplator probe \(advisory\):\n?/, "");
+			const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+			box.addChild(new Text(theme.fg("thinkingHigh", `${theme.bold("◆ CONTEMPLATOR PROBE")}\n${content}`), 0, 0));
+			return box;
+		});
+		this.pi.registerMessageRenderer(REVIEW_PROPOSAL_MESSAGE, (message, _options, theme) => {
+			const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+			box.addChild(new Text(theme.fg("thinkingHigh", `${theme.bold("◆ CONTEMPLATOR REVIEW")}\n${customMessageText(message.content)}`), 0, 0));
+			return box;
+		});
 		this.runtime.setMemoryUpdateListener((ctx) => this.withDebugContext(ctx, () => this.observeTurn(ctx)));
-		const restoreSessionBranch = (_event: any, ctx: ExtensionContext) => {
+		this.pi.on("session_start", (event: any, ctx: ExtensionContext) => {
 			this.sessionGeneration++;
-			this.restore(ctx, true);
-		};
-		this.pi.on("session_start", restoreSessionBranch);
-		this.pi.on("session_tree", restoreSessionBranch);
+			// AgentSession preserves its steering queue across extension reloads. An
+			// undelivered tracking entry therefore still has a live queued message;
+			// restoring it here would enqueue the same probe a second time.
+			const reload = event?.reason === "reload";
+			this.restore(ctx, true, reload, reload);
+		});
+		this.pi.on("session_tree", (_event: any, ctx: ExtensionContext) => {
+			this.sessionGeneration++;
+			// Pending steering messages remain queued while navigating the tree.
+			this.restore(ctx, true, true);
+		});
 		this.pi.on("session_shutdown", () => {
 			this.sessionGeneration++;
 			this.history = [];
@@ -172,7 +202,7 @@ export class Contemplator {
 			this.resumedReviewIds.clear();
 			this.reviewerSessions.clear();
 			this.deliveredProbeIds.clear();
-			this.requeuedProbeIds.clear();
+			this.queuedProbeIds.clear();
 			this.latestCtx = undefined;
 			this.turnsSinceRun = 0;
 			this.restoredTipId = undefined;
@@ -220,7 +250,7 @@ export class Contemplator {
 		}, fn);
 	}
 
-	private restore(ctx: MemoryUpdateCtx, resetTracking = false): void {
+	private restore(ctx: MemoryUpdateCtx, resetTracking = false, retainQueuedIds = false, skipUndeliveredRestore = false): void {
 		this.latestCtx = ctx;
 		const entries = ctx.sessionManager.getBranch() as Entry[];
 		const tipId = entries.at(-1)?.id;
@@ -229,7 +259,7 @@ export class Contemplator {
 		this.history = [];
 		if (resetTracking) {
 			this.deliveredProbeIds.clear();
-			this.requeuedProbeIds.clear();
+			if (!retainQueuedIds) this.queuedProbeIds.clear();
 			this.inFlightReviewIds.clear();
 			this.resolvingReviewIds.clear();
 			this.resumedReviewIds.clear();
@@ -312,8 +342,7 @@ export class Contemplator {
 		}
 		this.restoredTipId = tipId;
 		for (const [probeId, question] of undeliveredSuggestions) {
-			if (queuedProbeIds.has(probeId) || this.requeuedProbeIds.has(probeId)) continue;
-			this.requeuedProbeIds.add(probeId);
+			if (skipUndeliveredRestore || queuedProbeIds.has(probeId) || this.queuedProbeIds.has(probeId)) continue;
 			this.queueProbe(ctx, question, "restore", probeId);
 		}
 		if (resetTracking) void this.resumePendingReviews(ctx);
@@ -568,9 +597,13 @@ export class Contemplator {
 		this.pi.sendMessage({
 			customType: CONTEMPLATOR_SUGGESTION,
 			content: `Background contemplator probe (advisory):\n${question}`,
-			display: false,
+			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", {
@@ -646,7 +679,7 @@ export class Contemplator {
 				debugLog(result.outcome === "proposal" ? "reviewer.proposal_created" : "reviewer.no_proposal", { reviewRequestId: request.id, reviewMemoryId: result.id, scope: result.scope });
 				if (result.outcome === "proposal") {
 					const notice = `BACKGROUND ${result.scope.toUpperCase()} REVIEW PROPOSAL [${result.id}]\n\n${result.summary}\n\nRecall memory [${result.id}] to read the full conceptual proposal when it is relevant.\n\nThis is advisory. Evaluate it against the actual environment and current work.`;
-					this.pi.sendMessage({ customType: "om.review.proposal", content: notice, display: false, details: { version: 1, reviewRequestId: request.id, reviewMemoryId: result.id, scope: result.scope } }, { deliverAs: "steer", triggerTurn: false });
+					this.pi.sendMessage({ customType: REVIEW_PROPOSAL_MESSAGE, content: notice, display: this.runtime.config.showContemplatorMessages, details: { version: 1, reviewRequestId: request.id, reviewMemoryId: result.id, scope: result.scope } }, { deliverAs: "steer", triggerTurn: false });
 					this.pi.appendEntry(OM_REVIEWER_NOTICE, { version: 1, reviewRequestId: request.id, reviewMemoryId: result.id, scope: result.scope, content: notice });
 					this.markTipPersisted(ctx);
 					debugLog("reviewer.primary_notice_queued", { reviewRequestId: request.id, reviewMemoryId: result.id });

package/src/agents/reviewer/agent.ts

@@ -71,6 +71,27 @@ function assistantOutputTokens(messages: AgentMessage[]): number {
 	return total;
 }
 
+function completeReview(request: StructuralReviewRequest, terminal: ReviewTerminalResult): ReviewResult {
+	return {
+		...terminal,
+		id: hashId(`${request.id}:${JSON.stringify(terminal)}:${Date.now()}`),
+		version: 1,
+		reviewRequestId: request.id,
+		createdAt: Date.now(),
+		requestedBy: "contemplator",
+	} as ReviewResult;
+}
+
+function budgetExhaustedResult(request: StructuralReviewRequest): ReviewResult {
+	return completeReview(request, {
+		outcome: "no_proposal",
+		scope: request.scope,
+		reason: "The reviewer exhausted its lifetime output-token budget before recording a terminal proposal decision.",
+		evidenceReviewed: "The persisted reviewer transcript was retained, but no terminal evidence assessment was recorded before the budget was exhausted.",
+		reconsiderIf: "A new review can be requested with a narrower scope or a smaller evidence set.",
+	});
+}
+
 export async function runStructuralReview(args: RunStructuralReviewArgs): Promise<ReviewResult | undefined> {
 	let terminal: ReviewTerminalResult | undefined;
 	const acceptTerminal = (candidate: ReviewTerminalResult): void => {
@@ -98,7 +119,7 @@ export async function runStructuralReview(args: RunStructuralReviewArgs): Promis
 	// Usage on persisted assistant messages makes this a lifetime request budget,
 	// rather than a fresh allowance on each session/tree resumption.
 	let totalOutputTokens = assistantOutputTokens(history);
-	if (totalOutputTokens >= REVIEWER_TOTAL_TOKEN_LIMIT) return undefined;
+	if (totalOutputTokens >= REVIEWER_TOTAL_TOKEN_LIMIT) return budgetExhaustedResult(args.request);
 
 	// Persist both the user continuation and the returned messages immediately.
 	// This makes the transcript sufficient to resume a review after shutdown.
@@ -175,13 +196,10 @@ export async function runStructuralReview(args: RunStructuralReviewArgs): Promis
 		progress = await runOnce(keepGoing);
 		invocations++;
 	}
-	if (!terminal) return undefined;
-	return {
-		...terminal,
-		id: hashId(`${args.request.id}:${JSON.stringify(terminal)}:${Date.now()}`),
-		version: 1,
-		reviewRequestId: args.request.id,
-		createdAt: Date.now(),
-		requestedBy: "contemplator",
-	} as ReviewResult;
+	if (!terminal) {
+		return totalOutputTokens >= REVIEWER_TOTAL_TOKEN_LIMIT
+			? budgetExhaustedResult(args.request)
+			: undefined;
+	}
+	return completeReview(args.request, terminal);
 }

package/src/commands/settings.ts

@@ -10,7 +10,7 @@ type ModelRegistryLike = {
 	getAll(): Array<{ provider: string; id: string }>;
 };
 type NumberSetting = "observeAfterTokens" | "reflectAfterTokens" | "compactAfterTokens" | "observerChunkMaxTokens" | "observationsPoolMaxTokens" | "observationsPoolTargetTokens" | "agentMaxTurns" | "contemplatorMinNewObservations" | "contemplatorMinNewReflections" | "contemplatorMinTurns";
-type BooleanSetting = "contemplatorEnabled" | "reviewerEnabled" | "compactionObserverEnabled" | "showWorkerNotifications" | "passive" | "debugLog";
+type BooleanSetting = "contemplatorEnabled" | "showContemplatorMessages" | "reviewerEnabled" | "compactionObserverEnabled" | "showWorkerNotifications" | "passive" | "debugLog";
 
 function modelLabel(model: ConfiguredModel | undefined): string {
 	return model ? `${model.provider}/${model.id}` : "current session model";
@@ -175,8 +175,13 @@ export function registerSettingsCommand(pi: ExtensionAPI, runtime: Runtime): voi
 			ctx.ui.notify(`Structural reviewer: ${argument.endsWith("on") ? "enabled" : "disabled"} for this session.`, "info");
 			return;
 		}
+		if (argument === "messages on" || argument === "messages off") {
+			appendSettings(pi, runtime, { showContemplatorMessages: argument.endsWith("on") });
+			ctx.ui.notify(`Contemplator messages: ${argument.endsWith("on") ? "visible" : "hidden"} for this session.`, "info");
+			return;
+		}
 		if (argument) {
-			ctx.ui.notify("Usage: /om:settings [on|off|reviewer on|reviewer off|compaction on|compaction off]", "info");
+			ctx.ui.notify("Usage: /om:settings [on|off|messages on|messages off|reviewer on|reviewer off|compaction on|compaction off]", "info");
 			return;
 		}
 
@@ -185,6 +190,7 @@ export function registerSettingsCommand(pi: ExtensionAPI, runtime: Runtime): voi
 			const choice = await ctx.ui.select("Observational memory settings (session overrides)", [
 				`Contemplation: ${scalarLabel(runtime, "contemplatorEnabled")}`,
 				`Contemplation model: ${hasOverride(settings, "contemplatorModel") ? modelLabel(runtime.config.contemplatorModel) : `default (${modelLabel(runtime.getDefaultConfig().contemplatorModel)})`}`,
+				`Contemplator messages visible: ${scalarLabel(runtime, "showContemplatorMessages")}`,
 				`Structural reviewer: ${scalarLabel(runtime, "reviewerEnabled")}`,
 				`Structural reviewer model: ${hasOverride(settings, "reviewerModel") ? modelLabel(runtime.config.reviewerModel) : `default (${modelLabel(runtime.getDefaultConfig().reviewerModel)})`}`,
 				`Compaction observer: ${scalarLabel(runtime, "compactionObserverEnabled")}`,
@@ -208,6 +214,7 @@ export function registerSettingsCommand(pi: ExtensionAPI, runtime: Runtime): voi
 			]);
 			if (!choice || choice === "Done") return;
 			if (choice.startsWith("Contemplation:")) appendSettings(pi, runtime, { contemplatorEnabled: !runtime.config.contemplatorEnabled });
+			else if (choice.startsWith("Contemplator messages visible:")) appendSettings(pi, runtime, { showContemplatorMessages: !runtime.config.showContemplatorMessages });
 			else if (choice.startsWith("Structural reviewer:")) appendSettings(pi, runtime, { reviewerEnabled: !runtime.config.reviewerEnabled });
 			else if (choice.startsWith("Compaction observer:")) appendSettings(pi, runtime, { compactionObserverEnabled: !runtime.config.compactionObserverEnabled });
 			else if (choice.startsWith("Worker notifications:")) appendSettings(pi, runtime, { showWorkerNotifications: !runtime.config.showWorkerNotifications });

package/src/commands/status.ts

@@ -102,6 +102,7 @@ export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void
 				`Compaction observer:     ${runtime.config.compactionObserverEnabled === false ? "disabled" : "enabled"}`,
 				`Contemplator:             ${runtime.config.contemplatorEnabled ? "enabled" : "disabled"}`,
 				`Contemplator model:      ${runtime.config.contemplatorModel ? `${runtime.config.contemplatorModel.provider}/${runtime.config.contemplatorModel.id}` : "current session model"}`,
+				`Contemplator messages:   ${runtime.config.showContemplatorMessages ? "visible" : "hidden"}`,
 				`Structural reviewer:     ${runtime.config.reviewerEnabled === false ? "disabled" : "enabled"}`,
 				`Reviewer model:          ${runtime.config.reviewerModel ? `${runtime.config.reviewerModel.provider}/${runtime.config.reviewerModel.id}` : "current session model"}`,
 			];

package/src/config.ts

@@ -52,6 +52,8 @@ export interface Config {
 	compactionObserverEnabled: boolean;
 	contemplatorEnabled: boolean;
 	contemplatorModel?: ConfiguredModel;
+	/** Show contemplator probes and review notices in the chat transcript. */
+	showContemplatorMessages: boolean;
 	/** Allow the contemplator to commission scoped structural reviewers. */
 	reviewerEnabled: boolean;
 	/** Optional model override used only by short-lived structural reviewers. */
@@ -75,6 +77,7 @@ export const DEFAULTS: Config = {
 	passive: false,
 	compactionObserverEnabled: true,
 	contemplatorEnabled: true,
+	showContemplatorMessages: true,
 	reviewerEnabled: true,
 	contemplatorMinNewObservations: 8,
 	contemplatorMinNewReflections: 1,
@@ -223,6 +226,7 @@ function normalizeSettingsConfig(value: Record<string, unknown>): Partial<Config
 	if (typeof value.passive === "boolean") normalized.passive = value.passive;
 	if (typeof value.compactionObserverEnabled === "boolean") normalized.compactionObserverEnabled = value.compactionObserverEnabled;
 	if (typeof value.contemplatorEnabled === "boolean") normalized.contemplatorEnabled = value.contemplatorEnabled;
+	if (typeof value.showContemplatorMessages === "boolean") normalized.showContemplatorMessages = value.showContemplatorMessages;
 	if (typeof value.reviewerEnabled === "boolean") normalized.reviewerEnabled = value.reviewerEnabled;
 	if (typeof value.debugLog === "boolean") normalized.debugLog = value.debugLog;
 	const model = normalizeModel(value.model);

package/src/runtime.ts

@@ -35,7 +35,7 @@ export type SessionSettings = Partial<Pick<Config,
 	| "observeAfterTokens" | "reflectAfterTokens" | "observerChunkMaxTokens" | "compactAfterTokens"
 	| "compactAfterTokensMode" | "compactAfterTokensRatio"
 	| "observationsPoolMaxTokens" | "observationsPoolTargetTokens" | "agentMaxTurns"
-	| "showWorkerNotifications" | "passive" | "compactionObserverEnabled" | "contemplatorEnabled" | "reviewerEnabled"
+	| "showWorkerNotifications" | "passive" | "compactionObserverEnabled" | "contemplatorEnabled" | "showContemplatorMessages" | "reviewerEnabled"
 	| "contemplatorMinNewObservations" | "contemplatorMinNewReflections" | "contemplatorMinTurns" | "debugLog"
 >> & {
 	/** null explicitly means use the configured/session model. */
@@ -108,7 +108,7 @@ export function computeSessionSettings(entries: readonly unknown[]): SessionSett
 		if (!source || typeof source !== "object") return;
 		const data = source as Record<string, unknown>;
 		const booleanKeys = [
-			"showWorkerNotifications", "passive", "compactionObserverEnabled", "contemplatorEnabled", "reviewerEnabled", "debugLog",
+			"showWorkerNotifications", "passive", "compactionObserverEnabled", "contemplatorEnabled", "showContemplatorMessages", "reviewerEnabled", "debugLog",
 		] as const;
 		const numberKeys = [
 			"observeAfterTokens", "reflectAfterTokens", "observerChunkMaxTokens", "compactAfterTokens",