@matthewfl/pi-contemplator 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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;
@@ -252,17 +261,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") {
@@ -572,7 +606,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 +620,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 +680,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 +713,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";