@matthewfl/pi-contemplator 0.0.1 → 0.0.3

package/package.json

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

@@ -27,7 +27,16 @@ type Intervention =
 	| { kind: "probe"; question: string }
 	| { kind: "review"; request: Omit<StructuralReviewRequest, "createdAt" | "requestedBy"> };
 
-type ReviewerSession = { scope: StructuralReviewRequest["scope"]; history: AgentMessage[] };
+type ReviewerSession = {
+	scope: StructuralReviewRequest["scope"];
+	history: AgentMessage[];
+	/** Latest compact checkpoint; older transcript content stays in referenced append-only entries. */
+	checkpointEntryId?: string;
+	/** Reviewer message entries appended since checkpointEntryId. */
+	messageEntryIds: string[];
+	/** Message-entry ids already folded into `history` in this live session (restore re-walk guard). */
+	foldedEntryIds: Set<string>;
+};
 
 type QueueStructuralReviewOptions = {
 	ctx: MemoryUpdateCtx;
@@ -134,7 +143,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;
@@ -144,12 +154,19 @@ export class Contemplator {
 
 	register(): void {
 		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++;
+			// 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++;
-			this.restore(ctx, true);
-		};
-		this.pi.on("session_start", restoreSessionBranch);
-		this.pi.on("session_tree", restoreSessionBranch);
+			// Pending steering messages remain queued while navigating the tree.
+			this.restore(ctx, true, true);
+		});
 		this.pi.on("session_shutdown", () => {
 			this.sessionGeneration++;
 			this.history = [];
@@ -163,7 +180,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;
@@ -211,7 +228,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;
@@ -220,7 +237,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();
@@ -252,17 +269,42 @@ export class Contemplator {
 				}
 			}
 			if (entry.customType === OM_REVIEWER_STATE && entry.data && typeof entry.data === "object") {
-				const state = entry.data as { reviewRequestId?: unknown; scope?: unknown; history?: unknown };
-				if (typeof state.reviewRequestId === "string" && (state.scope === "workflow" || state.scope === "software") && Array.isArray(state.history)) {
-					this.reviewerSessions.set(state.reviewRequestId, { scope: state.scope, history: state.history.filter((message): message is AgentMessage => !!message && typeof message === "object") });
+				const state = entry.data as { version?: unknown; reviewRequestId?: unknown; scope?: unknown; history?: unknown; messageEntryIds?: unknown };
+				if (typeof state.reviewRequestId === "string" && (state.scope === "workflow" || state.scope === "software")) {
+					if (state.version === 1 && Array.isArray(state.history)) {
+						// Backward compatibility for the old, expensive full-transcript snapshots.
+						this.reviewerSessions.set(state.reviewRequestId, {
+							scope: state.scope,
+							history: state.history.filter((message): message is AgentMessage => !!message && typeof message === "object"),
+							checkpointEntryId: entry.id,
+							messageEntryIds: [],
+							foldedEntryIds: new Set(),
+						});
+					} else if (state.version === 2 && Array.isArray(state.messageEntryIds) && state.messageEntryIds.every((id) => typeof id === "string")) {
+						// V2 checkpoints contain references only. The referenced state/messages
+						// have already been folded while walking this append-only branch.
+						const session = this.reviewerSessions.get(state.reviewRequestId) ?? { scope: state.scope, history: [], messageEntryIds: [], foldedEntryIds: new Set() };
+						session.checkpointEntryId = entry.id;
+						session.messageEntryIds = [];
+						this.reviewerSessions.set(state.reviewRequestId, session);
+					}
 				}
 			}
 			if (entry.customType === OM_REVIEWER_MESSAGE && entry.data && typeof entry.data === "object") {
 				const data = entry.data as { reviewRequestId?: unknown; scope?: unknown; message?: unknown };
 				if (typeof data.reviewRequestId === "string" && (data.scope === "workflow" || data.scope === "software") && data.message && typeof data.message === "object") {
-					const session = this.reviewerSessions.get(data.reviewRequestId) ?? { scope: data.scope, history: [] };
-					session.history.push(data.message as AgentMessage);
-					this.reviewerSessions.set(data.reviewRequestId, session);
+					let session = this.reviewerSessions.get(data.reviewRequestId);
+					if (!session) {
+						session = { scope: data.scope, history: [], messageEntryIds: [], foldedEntryIds: new Set() };
+						this.reviewerSessions.set(data.reviewRequestId, session);
+					}
+					// restore() re-walks the whole branch whenever the tip moves
+					// (turn_end), so fold each message entry at most once per live session.
+					if (!session.foldedEntryIds.has(entry.id)) {
+						session.foldedEntryIds.add(entry.id);
+						session.history.push(data.message as AgentMessage);
+						session.messageEntryIds.push(entry.id);
+					}
 				}
 			}
 			if (entry.customType === CONTEMPLATOR_SUGGESTION && entry.data && typeof entry.data === "object") {
@@ -278,8 +320,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);
@@ -537,6 +578,10 @@ export class Contemplator {
 			display: false,
 			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", {
@@ -572,7 +617,7 @@ export class Contemplator {
 		this.resumedReviewIds.add(request.id);
 		this.inFlightReviewIds.add(request.id);
 		if (key) this.inFlightReviewKeys.add(key);
-		const session = this.reviewerSessions.get(request.id) ?? { scope: request.scope, history: options.history ?? [] };
+		const session = this.reviewerSessions.get(request.id) ?? { scope: request.scope, history: options.history ?? [], messageEntryIds: [], foldedEntryIds: new Set() };
 		this.reviewerSessions.set(request.id, session);
 		const task = this.runtime.launchReviewTask(ctx, async () => {
 			try {
@@ -586,9 +631,12 @@ export class Contemplator {
 						if (sessionGeneration !== this.sessionGeneration || !this.reviewIsPending(ctx, request.id)) return;
 						for (const message of messages) {
 							session.history.push(message);
-							this.pi.appendEntry(OM_REVIEWER_MESSAGE, { version: 1, reviewRequestId: request.id, scope: request.scope, message });
+							const entryId = this.appendEntryWithId(ctx, OM_REVIEWER_MESSAGE, { version: 1, reviewRequestId: request.id, scope: request.scope, message }, request.id);
+							if (entryId) {
+								session.foldedEntryIds.add(entryId);
+								session.messageEntryIds.push(entryId);
+							}
 						}
-						if (messages.length > 0) this.markTipPersisted(ctx);
 					},
 				});
 				if (sessionGeneration !== this.sessionGeneration) {
@@ -643,10 +691,17 @@ export class Contemplator {
 
 	private persistReviewerStates(ctx: MemoryUpdateCtx): void {
 		for (const [reviewRequestId, session] of this.reviewerSessions) {
-			if (session.history.length === 0) continue;
-			this.pi.appendEntry(OM_REVIEWER_STATE, { version: 1, reviewRequestId, scope: session.scope, history: session.history });
+			if (session.messageEntryIds.length === 0) continue;
+			const checkpointEntryId = this.appendEntryWithId(ctx, OM_REVIEWER_STATE, {
+				version: 2,
+				reviewRequestId,
+				scope: session.scope,
+				previousStateEntryId: session.checkpointEntryId,
+				messageEntryIds: session.messageEntryIds,
+			}, reviewRequestId);
+			if (checkpointEntryId) session.checkpointEntryId = checkpointEntryId;
+			session.messageEntryIds = [];
 		}
-		if (this.reviewerSessions.size > 0) this.markTipPersisted(ctx);
 	}
 
 	private async resumePendingReviews(ctx: MemoryUpdateCtx): Promise<void> {
@@ -669,8 +724,27 @@ export class Contemplator {
 		}
 	}
 
-	private markTipPersisted(ctx: MemoryUpdateCtx): void {
+	private markTipPersisted(ctx: MemoryUpdateCtx): string | undefined {
 		this.restoredTipId = (ctx.sessionManager.getBranch() as Entry[]).at(-1)?.id;
+		return this.restoredTipId;
+	}
+
+	/**
+	 * Append a custom entry and return the id of the entry just written, or
+	 * undefined when it cannot be attributed. pi.appendEntry() does not return
+	 * the entry id, so the branch is diffed around the synchronous append and the
+	 * candidate is matched by customType + reviewRequestId. This never credits a
+	 * concurrently-appended foreign entry reached via the branch tail. A failed
+	 * attribution is harmless: restore rebuilds transcripts from the durable
+	 * om.reviewer.message entries themselves and only skips a checkpoint.
+	 */
+	private appendEntryWithId(ctx: MemoryUpdateCtx, customType: string, data: Record<string, unknown>, reviewRequestId: string): string | undefined {
+		const branch = ctx.sessionManager.getBranch() as readonly Entry[];
+		const before = branch.length;
+		this.pi.appendEntry(customType, data);
+		const added = (ctx.sessionManager.getBranch() as readonly Entry[]).slice(before);
+		const own = added.find((entry) => entry.customType === customType && (entry.data as { reviewRequestId?: unknown } | undefined)?.reviewRequestId === reviewRequestId);
+		return own?.id;
 	}
 
 	private async compactHistory(model: Model<any>, apiKey: string, headers: Record<string, string> | undefined, sessionGeneration: number): Promise<void> {

package/src/session-ledger/types.ts

@@ -5,7 +5,7 @@ export const OM_REVIEW_REQUEST = "om.review.request";
 export const OM_REVIEW_RESULT = "om.review.result";
 /** Persisted assistant/tool output from a short-lived structural reviewer. */
 export const OM_REVIEWER_MESSAGE = "om.reviewer.message";
-/** Snapshot of a reviewer transcript retained across primary-session compaction. */
+/** Compact checkpoint referencing reviewer transcript entries across primary-session compaction. */
 export const OM_REVIEWER_STATE = "om.reviewer.state";
 /** Compact proposal notice queued for the primary agent. */
 export const OM_REVIEWER_NOTICE = "om.reviewer.notice";