@matthewfl/pi-contemplator 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/observer/agent.ts

@@ -1,4 +1,4 @@
-import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentMessage, type AgentTool } from "@earendil-works/pi-agent-core";
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "@earendil-works/pi-ai";
 import { streamSimple } from "@earendil-works/pi-ai/compat";
@@ -71,6 +71,16 @@ const RecordObservationsSchema = Type.Object({
 
 type RecordObservationsArgs = Static<typeof RecordObservationsSchema>;
 
+/** A terminal provider/agent-loop failure that must not advance observation coverage. */
+export class ObserverStreamError extends Error {
+	readonly stopReason: string;
+	constructor(stopReason: string, errorMessage?: string) {
+		super(`observer stream ended with stopReason "${stopReason}"${errorMessage ? `: ${errorMessage}` : ""}`);
+		this.name = "ObserverStreamError";
+		this.stopReason = stopReason;
+	}
+}
+
 function joinOrEmpty(items: string[]): string {
 	return items.length ? items.join("\n") : "(none yet)";
 }
@@ -98,14 +108,15 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 	if (!conversation) return undefined;
 
 	const accumulated = new Map<string, Observation>();
+	let rejectedTotal = 0;
+	let doneCalled = false;
 
 	const recordObservations: AgentTool<typeof RecordObservationsSchema> = {
 		name: "record_observations",
 		label: "Record observations",
 		description:
 			"Record a batch of new observations distilled from the conversation chunk. " +
-			"Call this multiple times as you work through the chunk. Stop calling when coverage is complete, " +
-			"then emit a short plain-text confirmation to end the run.",
+			"Call this multiple times as you work through the chunk, then call done alone when coverage is complete.",
 		parameters: RecordObservationsSchema,
 		execute: async (_id, params: RecordObservationsArgs) => {
 			let added = 0;
@@ -134,6 +145,7 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 				});
 				added++;
 			}
+			rejectedTotal += rejected;
 			const rejectedPart = rejected > 0
 				? ` ${rejected} observation${rejected === 1 ? "" : "s"} rejected for missing or invalid sourceEntryIds.`
 				: "";
@@ -142,11 +154,22 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 				(duplicates > 0 ? `(${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped).` : ".") +
 				rejectedPart +
 				` Total so far this run: ${accumulated.size}. ` +
-				`Continue if the chunk still has uncovered content; otherwise stop calling the tool and emit a short plain-text confirmation.`;
+				`Continue if the chunk still has uncovered content; otherwise call done alone.`;
 			return { content: [{ type: "text", text: ack }], details: { added, duplicates, rejected, total: accumulated.size } };
 		},
 	};
 
+	const doneTool: AgentTool<any> = {
+		name: "done",
+		label: "Done",
+		description: "Confirm that the entire provided conversation chunk has been inspected and all useful new observations have been recorded. Call alone, including when there is nothing new to record.",
+		parameters: Type.Object({}),
+		execute: async () => {
+			doneCalled = true;
+			return { content: [{ type: "text", text: "Observer coverage confirmed." }], details: {}, terminate: true };
+		},
+	};
+
 	const now = nowTimestamp();
 	const userText = `Current local time: ${now}
 
@@ -156,60 +179,86 @@ ${joinOrEmpty(priorSummaries)}
 CURRENT OBSERVATIONS:
 ${joinOrEmpty(priorObservations)}
 
-Compress the following new conversation chunk into observations by calling record_observations one or more times. Do not restate facts already present in current summaries or current observations. Prefer inline conversation timestamps when assigning times; fall back to the current local time above only if no message timestamp applies. Stop calling the tool and reply with a short plain-text confirmation once the chunk is fully covered.
+Compress the following new conversation chunk into observations by calling record_observations one or more times. Do not restate facts already present in current summaries or current observations. Prefer inline conversation timestamps when assigning times; fall back to the current local time above only if no message timestamp applies. When the chunk is fully covered, call done alone. If the chunk contains no useful new information, call done without calling record_observations.
 
 NEW CONVERSATION CHUNK:
 ${conversation}`;
 
-	const prompts: Message[] = [
-		{
-			role: "user",
-			content: [{ type: "text", text: userText }],
-			timestamp: Date.now(),
-		},
-	];
-
-	const context: AgentContext = {
-		systemPrompt: OBSERVER_SYSTEM,
-		messages: [],
-		tools: [recordObservations as AgentTool<any>],
+	const initialPrompt: Message = {
+		role: "user",
+		content: [{ type: "text", text: userText }],
+		timestamp: Date.now(),
 	};
 
 	const reasoning = (model as { reasoning?: unknown }).reasoning;
 	const thinkingLevel = args.thinkingLevel ?? "low";
 	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
 	let turnCount = 0;
-	const config: AgentLoopConfig = {
+	const baseConfig: AgentLoopConfig = {
 		model,
 		apiKey,
 		headers,
 		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
+		shouldStopAfterTurn: () => {
+			turnCount++;
+			return doneCalled || (effectiveMaxTurns !== undefined && turnCount >= effectiveMaxTurns);
+		},
 		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
-		...(effectiveMaxTurns !== undefined
-			? {
-				shouldStopAfterTurn: () => {
-					turnCount++;
-					return turnCount >= effectiveMaxTurns;
-				},
-			}
-			: {}),
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal, streamSimple);
-	for await (const event of stream) {
-		// Drain events; the tool's execute already collects records.
-		logAgentStreamError("observer", event);
-	}
-	const result = await stream.result();
-	if (args.recordUsage) {
+	const history: AgentMessage[] = [];
+	let terminalFailure: { stopReason: string; errorMessage?: string } | undefined;
+	const runInvocation = async (prompt: Message): Promise<void> => {
+		const context: AgentContext = {
+			systemPrompt: OBSERVER_SYSTEM,
+			messages: history.slice(),
+			tools: [recordObservations as AgentTool<any>, doneTool],
+		};
+		const stream = loop([prompt], context, baseConfig, signal, streamSimple);
+		for await (const event of stream) {
+			logAgentStreamError("observer", event);
+			const message = (event as { message?: { role?: string; stopReason?: string; errorMessage?: string } }).message;
+			if (message?.role === "assistant" && ["error", "aborted", "length"].includes(message.stopReason ?? "")) {
+				terminalFailure = { stopReason: message.stopReason!, errorMessage: message.errorMessage };
+			}
+		}
+		const result = await stream.result();
+		if (!Array.isArray(result)) return;
+		history.push(...result);
 		for (const message of result) {
-			if (message.role === "assistant" && message.usage) args.recordUsage(message.usage);
+			if (message.role === "assistant" && ["error", "aborted", "length"].includes(message.stopReason ?? "")) {
+				terminalFailure = { stopReason: message.stopReason, errorMessage: message.errorMessage };
+			}
+			if (args.recordUsage && message.role === "assistant" && message.usage) args.recordUsage(message.usage);
 		}
+	};
+
+	await runInvocation(initialPrompt);
+	if (accumulated.size === 0 && !doneCalled && !terminalFailure && rejectedTotal === 0) {
+		const reminder: Message = {
+			role: "user",
+			content: [{ type: "text", text: `You stopped without confirming coverage. Observations recorded so far: ${accumulated.size}. If the chunk is fully covered, call done now. Otherwise call record_observations for anything still missing, then call done.` }],
+			timestamp: Date.now(),
+		};
+		await runInvocation(reminder);
 	}
 
+	// Accepted observations remain useful even if the model neglected the final
+	// confirmation. Zero-observation coverage is advanced only by an explicit
+	// done call; failures, truncation, malformed records, and repeated prose do
+	// not silently discard the source chunk.
+	if (accumulated.size === 0 && terminalFailure) {
+		throw new ObserverStreamError(terminalFailure.stopReason, terminalFailure.errorMessage);
+	}
+	if (accumulated.size === 0 && rejectedTotal > 0) {
+		throw new ObserverStreamError("invalid_observations", `${rejectedTotal} proposed observation${rejectedTotal === 1 ? " was" : "s were"} rejected`);
+	}
+	if (accumulated.size === 0 && !doneCalled) {
+		throw new ObserverStreamError("incomplete", "observer stopped twice without recording observations or calling done");
+	}
 	if (accumulated.size === 0) return undefined;
 	return Array.from(accumulated.values());
 }

package/src/agents/observer/prompts.ts

@@ -15,7 +15,7 @@ How you work:
 2. Read the conversation chunk and identify what new information it contains.
 3. Call record_observations with a batch covering part (or all) of the chunk.
 4. Read the progress receipt. If content remains uncovered, call again. You may call the tool many times.
-5. When the chunk is fully covered, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.
+5. When the chunk is fully covered, call done alone. If there is no useful new information, call done without calling record_observations. Prose does not confirm coverage.
 
 What to emit:
 - Produce NEW observations for the new chunk only. Do not restate facts already present in summaries or current observations unless something has materially changed.
@@ -25,7 +25,7 @@ What to emit:
 - For every observation, choose retention independently from relevance. Recording the observation correctly comes first; never skip useful evidence because retention is uncertain.
 - Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.
 - Group repeated similar tool calls into a single observation rather than one per call.
-- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, simply do not call the tool and end with a plain-text confirmation.
+- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, do not call record_observations and call done alone. Ignoring a chunk or replying in prose does not mark it covered.
 
 Observation content rules:
 
@@ -125,4 +125,4 @@ A critical exact blocker can be contextual; a medium stable preference can be du
 
 Timestamp format: "YYYY-MM-DD HH:MM" (local time, 24-hour, to the minute). This goes in the timestamp field, not the content.
 
-Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count.`;
+Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count. Always finish by calling done alone.`;

package/src/commands/settings.ts

@@ -1,13 +1,14 @@
 import { DynamicBorder, getSelectListTheme } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, getKeybindings, Input, SelectList, Spacer, Text, fuzzyFilter, type Focusable, type SelectItem } from "@earendil-works/pi-tui";
-import type { ConfiguredModel } from "../config.js";
+import { OBSERVER_CHUNK_CONTEXT_RATIO, resolveObserverChunkMaxTokens, type ConfiguredModel } from "../config.js";
 import { OM_SETTINGS, type Runtime, type SessionSettings } from "../runtime.js";
 
 type ModelRegistryLike = {
 	refresh?(): Promise<void>;
 	getAvailable(): Array<{ provider: string; id: string }>;
 	getAll(): Array<{ provider: string; id: string }>;
+	find?(provider: string, id: string): { contextWindow?: number } | undefined;
 };
 type NumberSetting = "observeAfterTokens" | "compactAfterTokens" | "observerChunkMaxTokens" | "newMemoryPoolMaxTokens" | "oldMemoryPoolTargetTokens" | "agentMaxTurns" | "contemplatorMinNewObservations" | "contemplatorMinNewSummaries" | "contemplatorMinTurns" | "summarizerRetriggerTokens" | "summarizerSamplingThresholdTokens";
 type BooleanSetting = "contemplatorEnabled" | "showContemplatorMessages" | "reviewerEnabled" | "summarizerEnabled" | "compactionObserverEnabled" | "showWorkerNotifications" | "passive" | "debugLog";
@@ -44,6 +45,26 @@ function extensionEnabledLabel(runtime: Runtime): string {
 	return hasOverride(runtime.getSessionSettings(), "passive") ? String(enabled) : `${enabled} (default)`;
 }
 
+export function observerInputCapLabel(runtime: Runtime, contextWindow: number | undefined): string {
+	const explicit = runtime.config.observerChunkMaxTokens;
+	if (explicit !== undefined) {
+		return `${explicit.toLocaleString()} tokens${hasOverride(runtime.getSessionSettings(), "observerChunkMaxTokens") ? "" : " (default)"}`;
+	}
+	const cap = resolveObserverChunkMaxTokens(runtime.config, contextWindow);
+	if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {
+		const percent = OBSERVER_CHUNK_CONTEXT_RATIO * 100;
+		return `${percent}% of ${contextWindow.toLocaleString()} = ${cap.toLocaleString()} tokens (derived default)`;
+	}
+	return `${cap.toLocaleString()} tokens (fallback default; model context unavailable)`;
+}
+
+function observerContextWindow(runtime: Runtime, ctx: ExtensionContext): number | undefined {
+	const configured = runtime.config.model;
+	const registry = ctx.modelRegistry as unknown as ModelRegistryLike;
+	const model = configured ? registry.find?.(configured.provider, configured.id) ?? ctx.model : ctx.model;
+	return (model as { contextWindow?: number } | undefined)?.contextWindow;
+}
+
 interface ModelOption extends SelectItem {
 	configuredModel: ConfiguredModel | null;
 }
@@ -207,7 +228,7 @@ export function registerSettingsCommand(pi: ExtensionAPI, runtime: Runtime): voi
 				`Observe source during compaction: ${scalarLabel(runtime, "compactionObserverEnabled")}`,
 				`Observer and summarizer model: ${hasOverride(settings, "model") ? modelLabel(runtime.config.model) : `${modelLabel(runtime.getDefaultConfig().model)} (default)`}`,
 				`Observer source backlog trigger (tokens): ${scalarLabel(runtime, "observeAfterTokens")}`,
-				`Observer input cap (tokens): ${scalarLabel(runtime, "observerChunkMaxTokens")}`,
+				`Observer input cap: ${observerInputCapLabel(runtime, observerContextWindow(runtime, ctx))}`,
 				`Observer and summarizer max rounds: ${scalarLabel(runtime, "agentMaxTurns")}`,
 				`Automatic compaction source backlog trigger (tokens): ${scalarLabel(runtime, "compactAfterTokens")}`,
 				`Automatic compaction threshold mode: ${hasOverride(settings, "compactAfterTokensMode") ? runtime.config.compactAfterTokensMode : `${runtime.getDefaultConfig().compactAfterTokensMode} (default)`}`,
@@ -245,7 +266,7 @@ export function registerSettingsCommand(pi: ExtensionAPI, runtime: Runtime): voi
 			} else {
 				const numberChoice: Array<[string, NumberSetting, string]> = [
 					["Observer source backlog trigger (tokens):", "observeAfterTokens", "Observer source backlog trigger (tokens)"],
-					["Observer input cap (tokens):", "observerChunkMaxTokens", "Observer input cap (tokens)"],
+					["Observer input cap:", "observerChunkMaxTokens", "Observer input cap (tokens)"],
 					["Observer and summarizer max rounds:", "agentMaxTurns", "Observer and summarizer max rounds"],
 					["Automatic compaction source backlog trigger (tokens):", "compactAfterTokens", "Automatic compaction source backlog trigger (tokens)"],
 					["New memory pool protection budget (tokens):", "newMemoryPoolMaxTokens", "New memory pool protection budget (tokens)"],

package/src/config.ts

@@ -125,11 +125,11 @@ export const OBSERVER_CHUNK_MIN_TOKENS = 256;
 /**
  * Fraction of the memory model's context window used for the derived observer
  * chunk cap. Chunk sizes are estimated at ~4 chars/token, which can undercount
- * real tokens by up to ~4x on non-ASCII content, so 0.2 keeps even the worst
- * case at ~80% of the window with room left for the system prompt, prior
- * memory, and the response.
+ * real tokens substantially on non-ASCII content. The estimator remains
+ * approximate; the remaining 75% of the advertised window accommodates injected memory, the
+ * system prompt, and model output.
  */
-export const OBSERVER_CHUNK_CONTEXT_RATIO = 0.2;
+export const OBSERVER_CHUNK_CONTEXT_RATIO = 0.25;
 
 /**
  * Resolve the maximum estimated tokens the observer serializes into one chunk.
@@ -143,7 +143,7 @@ export const OBSERVER_CHUNK_CONTEXT_RATIO = 0.2;
  * after repeated observer failures, or when the extension is enabled mid-way
  * into a long session) makes every observer call fail, so coverage never
  * advances and the session can never recover. With the cap, oversized backlogs
- * are drained oldest-first across successive runs.
+ * are drained oldest-first across successive bounded passes.
  */
 export function resolveObserverChunkMaxTokens(config: Config, contextWindow: number | undefined): number {
 	if (config.observerChunkMaxTokens !== undefined && config.observerChunkMaxTokens > 0) {

package/src/hooks/consolidation-trigger.ts

@@ -227,12 +227,27 @@ export async function runConsolidationPipeline(
 	runtime.consolidationPhase = "observer";
 	runtime.lastObserverStartedAt = Date.now();
 	try {
-		const observerOutcome = await runObserverStage(pi, runtime, ctx, resolveModel, {
-			force: options.forceObserver === true,
-			entries: options.observerEntries,
-			contextGeneration,
-		});
-		if (observerOutcome === "abort") return;
+		// A large backlog is drained in bounded, oldest-first chunks. The normal
+		// trigger threshold controls when the batch stops; a static compaction
+		// snapshot is intentionally processed only once. Coverage must advance on
+		// every iteration, otherwise stop rather than spin on a failed chunk.
+		while (true) {
+			const beforeEntries = ctx.sessionManager.getBranch() as Entry[];
+			const beforeCoverage = latestCoverageIndex(beforeEntries, OM_OBSERVATIONS_RECORDED);
+			const observerOutcome = await runObserverStage(pi, runtime, ctx, resolveModel, {
+				force: options.forceObserver === true,
+				entries: options.observerEntries,
+				contextGeneration,
+			});
+			if (observerOutcome === "abort") return;
+			if (options.observerEntries) break;
+
+			const afterEntries = ctx.sessionManager.getBranch() as Entry[];
+			const afterCoverage = latestCoverageIndex(afterEntries, OM_OBSERVATIONS_RECORDED);
+			const remainingTokens = rawTokensSinceObservationCoverage(afterEntries);
+			if (afterCoverage <= beforeCoverage || remainingTokens < runtime.config.observeAfterTokens) break;
+			debugLog("observer.backlog_continue", { remainingTokens, afterCoverage });
+		}
 	} catch (error) {
 		debugLog("observer.error", { errorMessage: runtime.recordConsolidationStageError(ctx, "observer", error) });
 		return;
@@ -465,15 +480,6 @@ async function runObserverStage(
 		debugLog("observer.stale", { reason: "session_or_branch_changed" });
 		return "abort";
 	}
-	if (!observations || observations.length === 0) {
-		debugLog("observer.empty", { coversUpToId });
-		if (ctx.hasUI) ctx.ui?.notify(
-			"pi-contemplator: observer returned no observations",
-			"warning",
-		);
-		return "continue";
-	}
-
 	const currentEntries = ctx.sessionManager.getBranch() as Entry[];
 	let effectiveCoversUpToId = coversUpToId;
 	if (!currentEntries.some((entry) => entry.id === coversUpToId)) {
@@ -488,17 +494,24 @@ async function runObserverStage(
 			compactionId: compaction?.id,
 		});
 	}
-	const data = buildObservationsRecordedData(observations, effectiveCoversUpToId);
+	const accepted = observations ?? [];
+	const data = buildObservationsRecordedData(accepted, effectiveCoversUpToId);
 	if (!data) return "continue";
-	debugLog("observer.records", {
-		count: observations.length,
-		observationTokens: observations.reduce((sum, observation) => sum + observation.tokenCount, 0),
+	debugLog(accepted.length > 0 ? "observer.records" : "observer.coverage_only", {
+		count: accepted.length,
+		observationTokens: accepted.reduce((sum, observation) => sum + observation.tokenCount, 0),
 		coversUpToId: effectiveCoversUpToId,
 	});
+	// A clean zero-observation verdict is still successful coverage. Persist an
+	// empty batch so the next bounded pass starts after this chunk instead of
+	// retrying the same low-information source forever. Failures throw above and
+	// therefore never reach this coverage commit.
 	appendEntry(pi, OM_OBSERVATIONS_RECORDED, data);
-	debugLog("observer.appended", { count: observations.length, coversUpToId: effectiveCoversUpToId });
+	debugLog("observer.appended", { count: accepted.length, coversUpToId: effectiveCoversUpToId });
 	if (shouldNotifyWorker(runtime, ctx)) ctx.ui?.notify(
-		`pi-contemplator: ${observations.length} observation${observations.length === 1 ? "" : "s"} recorded`,
+		accepted.length > 0
+			? `pi-contemplator: ${accepted.length} observation${accepted.length === 1 ? "" : "s"} recorded`
+			: "pi-contemplator: observer found no new information; processed chunk marked covered",
 		"info",
 	);
 	return "continue";

package/src/session-ledger/progress.ts

@@ -74,7 +74,7 @@ function isNonEmptyArray(value: unknown): value is unknown[] {
 function isValidCoverageEntry(entry: Entry, customType: MemoryCoverageCustomType): entry is Entry & { data: { coversUpToId: string } } {
 	if (entry.type !== "custom" || entry.customType !== customType) return false;
 	if (!isObject(entry.data) || typeof entry.data.coversUpToId !== "string") return false;
-	if (customType === OM_OBSERVATIONS_RECORDED) return isNonEmptyArray(entry.data.observations);
+	if (customType === OM_OBSERVATIONS_RECORDED) return Array.isArray(entry.data.observations);
 	return customType === OM_SUMMARIZER_COMMIT && isNonEmptyArray(entry.data.summaries);
 }
 

package/src/session-ledger/types.ts

@@ -235,7 +235,6 @@ export function isObservationsRecordedData(value: unknown): value is Observation
 	if (!isPlainRecord(value)) return false;
 	return (
 		Array.isArray(value.observations) &&
-		value.observations.length > 0 &&
 		value.observations.every(isObservation) &&
 		isNonEmptyString(value.coversUpToId)
 	);
@@ -345,7 +344,7 @@ export function buildObservationsRecordedData(
 	observations: Observation[],
 	coversUpToId: string,
 ): ObservationsRecordedEntryData | undefined {
-	if (observations.length === 0 || !isNonEmptyString(coversUpToId)) return undefined;
+	if (!isNonEmptyString(coversUpToId)) return undefined;
 	const candidate = { observations, coversUpToId };
 	return isObservationsRecordedData(candidate) ? candidate : undefined;
 }