pi-observational-memory 3.0.3 → 3.1.1

package/README.md

@@ -173,6 +173,8 @@ This extension is especially useful when the session contains decisions that sho
 
 ## Install
 
+Requires Pi 0.81.0 or newer. Proactive compaction uses the `agent_settled` lifecycle event introduced in that release.
+
 ```bash
 pi install npm:pi-observational-memory
 ```
@@ -218,6 +220,7 @@ A typical config:
       "id": "google/gemma-4-31b-it",
       "thinking": "low"
     },
+    "showWorkerNotifications": true,
     "passive": false,
     "debugLog": false
   }
@@ -226,12 +229,14 @@ A typical config:
 
 Most users can start with the defaults and tune only if they have a specific reason.
 
+If your memory model is a local llama.cpp server, size `agentMaxTokens` so that a worst-case request (observer chunk + prior memory + system prompt + the full response budget) fits inside the server's context: slot KV is shared between the main session's retained cache and concurrent sub-agent requests, so an over-budget sub-agent request fails with `500 "Context size has been exceeded."` and the affected memory run aborts. For example, on a 64K-slot server, pairing `"agentMaxTokens": 8192` with a low `observerChunkMaxTokens` keeps sub-agent requests well inside the window.
+
 ### Scaling compaction to the model's context window
 
 By default `compactAfterTokensMode` is `"calibrated"`, so the proactive
-compaction trigger fires at the fixed `compactAfterTokens` value (81,000 by
-default). That is backwards-compatible and works well for typical ~128K–200K
-context models.
+compaction trigger uses the fixed `compactAfterTokens` estimated source-entry
+threshold (81,000 by default). This preserves the pre-PR #40 compaction metric
+for typical ~128K–200K context models.
 
 On a large-context model (e.g. 1M tokens) the calibrated default preempts
 compaction at ~81K, wasting most of the window. Switch to `"ratio"` mode to let
@@ -249,8 +254,11 @@ the trigger scale with the active model's `contextWindow`:
 
 In ratio mode the effective threshold is
 `floor(model.contextWindow * compactAfterTokensRatio)` (clamped to a minimum of
-1). With the example above, a 1,000,000-token window compacts at ~500,000 raw
-tokens; a 200,000-token window compacts at ~100,000.
+1). With the example above, a 1,000,000-token window compacts after about
+500,000 estimated source-entry tokens after the latest compaction boundary; a
+200,000-token window uses about 100,000. The threshold counts source entries,
+not Pi's system prompt, tool schemas, or provider accounting. Pi's native
+window-pressure compaction remains independent.
 
 `compactAfterTokensRatio` is user-tunable precisely because **context window ≠
 attention**. Some models advertise a large window but degrade at long range; set
@@ -268,14 +276,17 @@ on the `Next compaction` line regardless of mode.
 | Setting                     | Default       | Meaning                                                                                           |
 | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
 | `observeAfterTokens`        | `10000`       | Raw/source token threshold for observation runs.                                                  |
+| `observerChunkMaxTokens`    | derived       | Max estimated tokens serialized into one observer chunk (minimum `256`). Unset: `floor(contextWindow * 0.2)` of the resolved memory model, or `60000` when the window is unknown. Larger backlogs drain oldest-first; a single over-budget source is sent as a marked head/tail excerpt while the original source remains in the session ledger. |
 | `reflectAfterTokens`        | `20000`       | Raw/source token threshold for reflection runs; successful reflection creates dropper opportunities. |
-| `compactAfterTokens`        | `81000`       | Raw/source token threshold for proactive auto-compaction (used directly in `"calibrated"` mode, and as the fallback in `"ratio"` mode). |
-| `compactAfterTokensMode`    | `"calibrated"`| `"calibrated"` uses `compactAfterTokens` directly (default, backwards-compatible). `"ratio"` scales the threshold by the active model's `contextWindow`. |
+| `compactAfterTokens`        | `81000`       | Estimated source-entry threshold for proactive auto-compaction, counted after the latest compaction boundary. |
+| `compactAfterTokensMode`    | `"calibrated"`| `"calibrated"` uses `compactAfterTokens` directly. `"ratio"` scales the source-entry threshold by the active model's `contextWindow`. |
 | `compactAfterTokensRatio`   | `0.68`        | In `"ratio"` mode, the threshold is `floor(contextWindow * ratio)`. Tunable because large windows do not always mean strong long-range attention. Must be in `(0, 1)`. |
 | `observationsPoolMaxTokens` | `20000`       | Observation-token budget used for compaction full-fold pressure.                                  |
 | `observationsPoolTargetTokens` | half of max | Active observation target used by post-reflection dropper maintenance.                            |
 | `agentMaxTurns`             | `16`          | Shared turn cap for background memory-agent loops.                                                |
+| `agentMaxTokens`            | `32000`       | Maximum output tokens requested for memory-agent loops (observer/reflector/dropper), clamped to the model's own `maxTokens` when available. Lower it for local servers with a modest context window, e.g. `8192`. |
 | `model`                     | session model | Optional memory-worker model override: `{ provider, id, thinking }`.                              |
+| `showWorkerNotifications`   | `true`        | Shows routine observer, reflector, and dropper progress notifications. Warnings and errors are unaffected. |
 | `passive`                   | `false`       | Disables proactive background observation, reflection, maintenance, and auto-compaction triggers. |
 | `debugLog`                  | `false`       | Writes opt-in per-session extension debug events to Pi's agent directory.                         |
 
@@ -287,8 +298,11 @@ Valid `model.thinking` values are:
 * `medium`
 * `high`
 * `xhigh`
+* `max`
 
-If no `model` is configured, memory workers use the session model.
+If no `model` is configured, memory workers use the session model, including custom `pi.registerProvider` APIs such as `cursor-sdk`. You do not need a second built-in provider (OpenAI, OpenRouter, …) for observational memory to run. Set `model` only when you want cheaper or faster workers than the coding agent.
+
+Set `showWorkerNotifications` to `false` to hide routine worker start and completion messages (including deliberate-empty observer info messages). Model fallback/unavailability, worker failures (including observer stream errors), compaction notifications, and explicit `/om:*` command output remain visible.
 
 `observationsPoolMaxTokens` and `observationsPoolTargetTokens` intentionally describe different pools. Max tokens control when compaction performs a full fold over visible memory. Target tokens control the folded active observation pool that the dropper maintains after successful reflection. If the target is omitted, it defaults to half of max.
 
@@ -320,14 +334,14 @@ flowchart TD
     Turn[turn_end]
     Observe[Capture observations]
     Reflect[Distill reflections]
-    AgentEnd[agent_end]
+    AgentSettled[agent_settled]
     Trigger[auto-compaction trigger]
     Compact[session_before_compact]
     Summary[visible memory for Pi]
 
     Turn -->|observation due| Observe
     Turn -->|reflection due| Reflect
-    AgentEnd -->|compactAfterTokens and idle| Trigger --> Compact --> Summary
+    AgentSettled -->|compactAfterTokens and idle| Trigger --> Compact --> Summary
 ```
 
 The high-level lifecycle:
@@ -340,6 +354,12 @@ The high-level lifecycle:
 
 The important part: compaction does not need to rethink the whole session from scratch.
 
+The proactive compaction threshold counts estimated source-entry tokens after
+the latest compaction boundary. It includes source entries retained by
+`firstKeptEntryId` and newer source entries, while memory ledger entries and
+compaction metadata contribute zero. `/om:status` uses the same metric. Pi's
+own window-pressure compaction remains independent.
+
 ---
 
 ## Current V3 behavior
@@ -348,7 +368,7 @@ Current behavior:
 
 * **Observation-centered memory.** The extension records useful session observations while you work.
 * **Durable reflections.** The extension distills stable facts that help the agent stay oriented over time.
-* **Fast compaction.** `session_before_compact` does not call a model or wait for background workers. It renders the current prepared memory state.
+* **Fast compaction.** When prepared V3 memory exists, `session_before_compact` renders it without calling a model or waiting for background workers. An empty V3 projection delegates to Pi's native summarizer instead of replacing prior context with an empty summary.
 * **Background memory work.** Observation and reflection work run from `turn_end` when their token clocks are due; dropper work runs only after successful reflection and prunes the folded active observation ledger toward `observationsPoolTargetTokens`.
 * **Source-backed recall.** Observations and reflections can be traced back through the `recall` tool.
 * **Visible/full views.** `/om:view` shows visible memory and `/om:view full` shows the full current memory state. Use `/om:status` for visible-vs-full drift and for the separate visible observation pool vs active observation pool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-observational-memory",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "Observational memory extension for pi — cache-friendly tiered compaction with observations and reflections.",
   "type": "module",
   "license": "MIT",
@@ -40,10 +40,10 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
+    "@earendil-works/pi-agent-core": "^0.81.0",
+    "@earendil-works/pi-ai": "^0.81.0",
+    "@earendil-works/pi-coding-agent": "^0.81.0",
+    "@earendil-works/pi-tui": "^0.81.0",
     "@types/node": "^22.0.0",
     "typebox": "^1.1.38",
     "typescript": "^5.6.0",

package/src/agents/dropper/agent.ts

@@ -4,6 +4,8 @@ import { Type } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
 import { debugLog } from "../../debug-log.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
+import { logAgentStreamError } from "../stream-errors.js";
+import { resolveWorkerStreamSimple, type StreamableModelRegistry, type WorkerStreamSimple } from "../worker-stream.js";
 import { reflectionToSummaryLine, type Observation, type Reflection } from "../../session-ledger/index.js";
 import { DROPPER_SYSTEM } from "./prompts.js";
 import {
@@ -37,15 +39,20 @@ export type { CoverageSummaryByRelevance, CoverageTransitionSummaryByRelevance,
 
 interface RunDropperArgs {
 	model: Model<any>;
-	apiKey: string;
+	apiKey?: string;
 	headers?: Record<string, string>;
+	env?: Record<string, string>;
 	reflections: Reflection[];
 	observations: Observation[];
 	targetTokens: number;
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
 	maxTurns?: number;
+	/** Maximum output tokens for the loop (defaults to {@link AGENT_LOOP_MAX_TOKENS}). */
+	maxOutputTokens?: number;
 	thinkingLevel?: ModelThinkingLevel;
+	modelRegistry?: StreamableModelRegistry;
+	streamSimple?: WorkerStreamSimple;
 }
 
 const RELEVANCE_DROP_RANK: Record<Observation["relevance"], number> = {
@@ -129,7 +136,7 @@ export function selectDropCandidates(
 }
 
 export async function runDropper(args: RunDropperArgs): Promise<string[] | undefined> {
-	const { model, apiKey, headers, reflections, observations, targetTokens, signal } = args;
+	const { model, apiKey, headers, env, reflections, observations, targetTokens, signal } = args;
 	if (observations.length === 0) return undefined;
 
 	const metrics = observationPoolMetrics(observations, targetTokens);
@@ -241,7 +248,8 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 		model,
 		apiKey,
 		headers,
-		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		env,
+		maxTokens: boundedMaxTokens(model, args.maxOutputTokens ?? AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
 		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
@@ -249,9 +257,16 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
-	for await (const _event of stream) {
+	const stream = loop(
+		prompts,
+		context,
+		config,
+		signal,
+		resolveWorkerStreamSimple(model, args.modelRegistry, args.streamSimple),
+	);
+	for await (const event of stream) {
 		// Tool execution collects candidate ids.
+		logAgentStreamError("dropper", event);
 	}
 	await stream.result();
 	const droppedIds = selectDropCandidates(proposedDropIds, observations, maxDropsAllowed, reflections);

package/src/agents/dropper/pool.ts

@@ -1,3 +1,4 @@
+import { observationLineTokenCount } from "../../tokens.js";
 import type { Observation } from "../../session-ledger/index.js";
 
 export type ObservationPoolMetrics = {
@@ -12,8 +13,11 @@ export type ObservationPoolMetrics = {
 	ready: boolean;
 };
 
-export function observationTokenSum(observations: readonly { tokenCount: number }[]): number {
-	return observations.reduce((sum, observation) => sum + observation.tokenCount, 0);
+export function observationTokenSum(observations: readonly Observation[]): number {
+	// Count the full rendered line (id + timestamp + relevance + content), not
+	// bare content: the pool budget caps how much observation text is re-rendered
+	// into future contexts, and every line carries metadata overhead.
+	return observations.reduce((sum, observation) => sum + observationLineTokenCount(observation), 0);
 }
 
 export function observationPoolFullness(observationTokens: number, targetTokens: number): number {

package/src/agents/observer/agent.ts

@@ -3,16 +3,19 @@ import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
 import { hashId } from "../../ids.js";
+import { logAgentStreamError } from "../stream-errors.js";
+import { resolveWorkerStreamSimple, type StreamableModelRegistry, type WorkerStreamSimple } from "../worker-stream.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";
 import { nowTimestamp, truncateRecordContent } from "../../serialize.js";
 import type { Observation, Relevance } from "../../session-ledger/index.js";
-import { estimateStringTokens } from "../../tokens.js";
+import { observationLineTokenCount } from "../../tokens.js";
 
 interface RunObserverArgs {
 	model: Model<any>;
-	apiKey: string;
+	apiKey?: string;
 	headers?: Record<string, string>;
+	env?: Record<string, string>;
 	priorReflections: string[];
 	priorObservations: string[];
 	chunk: string;
@@ -20,7 +23,11 @@ interface RunObserverArgs {
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
 	maxTurns?: number;
+	/** Maximum output tokens for the loop (defaults to {@link AGENT_LOOP_MAX_TOKENS}). */
+	maxOutputTokens?: number;
 	thinkingLevel?: ModelThinkingLevel;
+	modelRegistry?: StreamableModelRegistry;
+	streamSimple?: WorkerStreamSimple;
 }
 
 const RelevanceSchema = Type.Union([
@@ -60,6 +67,21 @@ const RecordObservationsSchema = Type.Object({
 
 type RecordObservationsArgs = Static<typeof RecordObservationsSchema>;
 
+/**
+ * Thrown when the agent loop ends with an API/stream failure (`stopReason`
+ * `"error"`/`"aborted"`) without recording anything. agent-core returns such
+ * runs normally, so without this the caller cannot tell a hard failure from a
+ * deliberate empty result (#32).
+ */
+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)";
 }
@@ -82,7 +104,7 @@ export function normalizeSourceEntryIds(
 }
 
 export async function runObserver(args: RunObserverArgs): Promise<Observation[] | undefined> {
-	const { model, apiKey, headers, priorReflections, priorObservations, chunk, allowedSourceEntryIds, signal } = args;
+	const { model, apiKey, headers, env, priorReflections, priorObservations, chunk, allowedSourceEntryIds, signal } = args;
 	const conversation = chunk.trim();
 	if (!conversation) return undefined;
 
@@ -118,7 +140,12 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 					timestamp: obs.timestamp,
 					relevance: obs.relevance as Relevance,
 					sourceEntryIds,
-					tokenCount: estimateStringTokens(content),
+					tokenCount: observationLineTokenCount({
+						id,
+						timestamp: obs.timestamp,
+						relevance: obs.relevance,
+						content,
+					}),
 				});
 				added++;
 			}
@@ -171,7 +198,8 @@ ${conversation}`;
 		model,
 		apiKey,
 		headers,
-		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		env,
+		maxTokens: boundedMaxTokens(model, args.maxOutputTokens ?? AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
 		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
@@ -186,12 +214,29 @@ ${conversation}`;
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
-	for await (const _event of stream) {
+	const stream = loop(
+		prompts,
+		context,
+		config,
+		signal,
+		resolveWorkerStreamSimple(model, args.modelRegistry, args.streamSimple),
+	);
+	let streamError: { stopReason: string; errorMessage?: string } | undefined;
+	for await (const event of stream) {
 		// Drain events; the tool's execute already collects records.
+		logAgentStreamError("observer", event);
+		// Watch for a terminal API/stream failure so it is not conflated with
+		// a deliberate empty result.
+		const message = (event as { message?: { role?: string; stopReason?: string; errorMessage?: string } }).message;
+		if (message?.role === "assistant" && (message.stopReason === "error" || message.stopReason === "aborted")) {
+			streamError = { stopReason: message.stopReason, errorMessage: message.errorMessage };
+		}
 	}
 	await stream.result();
 
-	if (accumulated.size === 0) return undefined;
+	if (accumulated.size === 0) {
+		if (streamError) throw new ObserverStreamError(streamError.stopReason, streamError.errorMessage);
+		return undefined;
+	}
 	return Array.from(accumulated.values());
 }

package/src/agents/reflector/agent.ts

@@ -4,6 +4,8 @@ import { Type } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
 import { debugLog } from "../../debug-log.js";
 import { hashId } from "../../ids.js";
+import { logAgentStreamError } from "../stream-errors.js";
+import { resolveWorkerStreamSimple, type StreamableModelRegistry, type WorkerStreamSimple } from "../worker-stream.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
 import { truncateRecordContent } from "../../serialize.js";
 import { REFLECTOR_SYSTEM } from "./prompts.js";
@@ -19,14 +21,19 @@ import {
 
 interface RunReflectorArgs {
 	model: Model<any>;
-	apiKey: string;
+	apiKey?: string;
 	headers?: Record<string, string>;
+	env?: Record<string, string>;
 	reflections: Reflection[];
 	observations: Observation[];
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
 	maxTurns?: number;
+	/** Maximum output tokens for the loop (defaults to {@link AGENT_LOOP_MAX_TOKENS}). */
+	maxOutputTokens?: number;
 	thinkingLevel?: ModelThinkingLevel;
+	modelRegistry?: StreamableModelRegistry;
+	streamSimple?: WorkerStreamSimple;
 }
 
 const RecordReflectionsSchema = Type.Object({
@@ -103,7 +110,7 @@ function normalizeReflectionContent(content: string): string | undefined {
 }
 
 export async function runReflector(args: RunReflectorArgs): Promise<Reflection[] | undefined> {
-	const { model, apiKey, headers, reflections, observations, signal } = args;
+	const { model, apiKey, headers, env, reflections, observations, signal } = args;
 	if (observations.length === 0) return undefined;
 
 	const coverageById = reflectionCoverageMap(observations, reflections);
@@ -174,7 +181,8 @@ export async function runReflector(args: RunReflectorArgs): Promise<Reflection[]
 		model,
 		apiKey,
 		headers,
-		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		env,
+		maxTokens: boundedMaxTokens(model, args.maxOutputTokens ?? AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
 		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
@@ -182,9 +190,16 @@ export async function runReflector(args: RunReflectorArgs): Promise<Reflection[]
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
-	for await (const _event of stream) {
+	const stream = loop(
+		prompts,
+		context,
+		config,
+		signal,
+		resolveWorkerStreamSimple(model, args.modelRegistry, args.streamSimple),
+	);
+	for await (const event of stream) {
 		// Tool execution collects records.
+		logAgentStreamError("reflector", event);
 	}
 	await stream.result();
 	const acceptedReflections = Array.from(accumulated.values());

package/src/agents/stream-errors.ts

@@ -0,0 +1,22 @@
+import type { AgentEvent } from "@earendil-works/pi-agent-core";
+import { debugLog } from "../debug-log.js";
+
+/**
+ * Surface LLM failures from an agent-loop event stream.
+ *
+ * When the underlying LLM call fails, the loop ends the stream with a final
+ * assistant message whose stopReason is "error" (or "aborted") — no exception
+ * is thrown. Without this hook the drain loops treat such runs exactly like
+ * "the model chose not to call the tool", which hides the real cause
+ * (rate limits, oversized prompts, auth failures, ...) from the debug log.
+ */
+export function logAgentStreamError(stage: "observer" | "reflector" | "dropper", event: AgentEvent): void {
+	if (event.type !== "message_end") return;
+	const message = event.message;
+	if (message.role !== "assistant") return;
+	if (message.stopReason !== "error" && message.stopReason !== "aborted") return;
+	debugLog(`${stage}.stream_error`, {
+		stopReason: message.stopReason,
+		errorMessage: message.errorMessage,
+	});
+}

package/src/agents/worker-stream.ts

@@ -0,0 +1,65 @@
+import type { AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { streamSimple as compatStreamSimple } from "@earendil-works/pi-ai/compat";
+
+export type WorkerStreamSimple = (
+	model: Model<any>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => AssistantMessageEventStream;
+
+/**
+ * Duck-typed subset of Pi's extension ModelRegistry.
+ *
+ * `streamSimple` is the host-composed path (Pi #8964). Until that lands on the
+ * facade, `getRegisteredProviderConfig` still exposes each `registerProvider`
+ * `streamSimple` handler, keyed by the extension provider id — match on
+ * `config.api === model.api`.
+ */
+export type StreamableModelRegistry = {
+	streamSimple?: WorkerStreamSimple;
+	getRegisteredProviderIds?: () => readonly string[];
+	getRegisteredProviderConfig?: (providerId: string) => {
+		api?: string;
+		streamSimple?: WorkerStreamSimple;
+	} | undefined;
+};
+
+/**
+ * Resolve the stream function background workers must pass to `agentLoop`.
+ *
+ * Direct `@earendil-works/pi-ai/compat` `streamSimple` only knows built-in API
+ * ids. Custom providers (`cursor-sdk`, `cliproxyapi-*`, commandcode, …) live on
+ * Pi's composed runtime. Using compat after a successful foreground turn is
+ * what crashes Pi with `No API provider registered for api: …` (#30).
+ */
+export function resolveWorkerStreamSimple(
+	model: Model<any>,
+	modelRegistry?: StreamableModelRegistry | null,
+	override?: WorkerStreamSimple,
+): WorkerStreamSimple {
+	if (override) return override;
+
+	const registryStream = modelRegistry?.streamSimple;
+	if (typeof registryStream === "function") {
+		return (nextModel, context, options) => registryStream(nextModel, context, options);
+	}
+
+	try {
+		if (
+			typeof modelRegistry?.getRegisteredProviderIds === "function"
+			&& typeof modelRegistry?.getRegisteredProviderConfig === "function"
+		) {
+			for (const providerId of modelRegistry.getRegisteredProviderIds()) {
+				const config = modelRegistry.getRegisteredProviderConfig(providerId);
+				const composed = config?.streamSimple;
+				if (config?.api === model.api && typeof composed === "function") {
+					return composed;
+				}
+			}
+		}
+	} catch {
+		// Incomplete host/test doubles still use the built-in compat dispatcher.
+	}
+
+	return compatStreamSimple;
+}

package/src/commands/status.ts

@@ -82,7 +82,7 @@ export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void
 				"── Activity ──",
 				`Next observation: ~${obsProgress.toLocaleString()} / ${runtime.config.observeAfterTokens.toLocaleString()} tokens (${pct(obsProgress, runtime.config.observeAfterTokens)}%)`,
 				`Next reflection:  ~${reflectionProgress.toLocaleString()} / ${runtime.config.reflectAfterTokens.toLocaleString()} tokens (${pct(reflectionProgress, runtime.config.reflectAfterTokens)}%)`,
-				`Next compaction:  ~${compactionProgress.toLocaleString()} / ${compactThreshold.toLocaleString()} tokens (${pct(compactionProgress, compactThreshold)}%)`,
+				`Next compaction:  ~${compactionProgress.toLocaleString()} / ${compactThreshold.toLocaleString()} estimated source tokens (${pct(compactionProgress, compactThreshold)}%)`,
 				`Visible observation pool: ~${visibleObservationTokens.toLocaleString()} / ${runtime.config.observationsPoolMaxTokens.toLocaleString()} tokens (${pct(visibleObservationTokens, runtime.config.observationsPoolMaxTokens)}%)`,
 				`Active observation pool: ~${activeObservationPool.observationTokens.toLocaleString()} / ${runtime.config.observationsPoolTargetTokens.toLocaleString()} target tokens (${pct(activeObservationPool.observationTokens, runtime.config.observationsPoolTargetTokens)}%)`,
 				`Reflection pool:         ~${visibleReflectionTokens.toLocaleString()} tokens`,

package/src/config.ts

@@ -33,13 +33,28 @@ export type CompactAfterTokensMode = "calibrated" | "ratio";
 export interface Config {
 	observeAfterTokens: number;
 	reflectAfterTokens: number;
+	/**
+	 * Maximum estimated source tokens serialized into a single observer chunk.
+	 * Unset (default) derives the cap from the resolved memory model's context
+	 * window; see {@link resolveObserverChunkMaxTokens}.
+	 */
+	observerChunkMaxTokens?: number;
 	compactAfterTokens: number;
 	compactAfterTokensMode: CompactAfterTokensMode;
 	compactAfterTokensRatio: number;
 	observationsPoolMaxTokens: number;
 	observationsPoolTargetTokens: number;
 	agentMaxTurns: number;
+	/**
+	 * Maximum output tokens requested for background memory-agent loops
+	 * (observer/reflector/dropper). Always clamped to the model's own
+	 * `maxTokens` when available. Lower it for local servers with a modest
+	 * context window, where concurrent sub-agent requests share KV with the
+	 * main session and the default 32K response budget can overflow the slot.
+	 */
+	agentMaxTokens: number;
 	model?: ConfiguredModel;
+	showWorkerNotifications: boolean;
 	passive: boolean;
 	debugLog: boolean;
 }
@@ -53,6 +68,8 @@ export const DEFAULTS: Config = {
 	observationsPoolMaxTokens: 20_000,
 	observationsPoolTargetTokens: 10_000,
 	agentMaxTurns: 16,
+	agentMaxTokens: 32_000,
+	showWorkerNotifications: true,
 	passive: false,
 	debugLog: false,
 };
@@ -76,7 +93,49 @@ export function resolveCompactAfterTokens(config: Config, contextWindow: number
 	return config.compactAfterTokens;
 }
 
-export const THINKING_LEVEL_VALUES: readonly ModelThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export const THINKING_LEVEL_VALUES: readonly ModelThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+/** Observer chunk cap used when no config is set and the model's context window is unknown. */
+export const OBSERVER_CHUNK_FALLBACK_MAX_TOKENS = 60_000;
+
+/** Smallest useful observer chunk: enough for labels, omission markers, and source context. */
+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.
+ */
+export const OBSERVER_CHUNK_CONTEXT_RATIO = 0.2;
+
+/**
+ * Resolve the maximum estimated tokens the observer serializes into one chunk.
+ *
+ * An explicit `observerChunkMaxTokens` config value always wins. Otherwise the
+ * cap is `floor(contextWindow * OBSERVER_CHUNK_CONTEXT_RATIO)` for the resolved
+ * memory model, falling back to {@link OBSERVER_CHUNK_FALLBACK_MAX_TOKENS} when
+ * the context window is unavailable.
+ *
+ * Without a cap, a backlog that outgrows the model's context window (e.g.
+ * 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.
+ */
+export function resolveObserverChunkMaxTokens(config: Config, contextWindow: number | undefined): number {
+	if (config.observerChunkMaxTokens !== undefined && config.observerChunkMaxTokens > 0) {
+		return Math.max(OBSERVER_CHUNK_MIN_TOKENS, config.observerChunkMaxTokens);
+	}
+	if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {
+		return Math.max(
+			OBSERVER_CHUNK_MIN_TOKENS,
+			Math.floor(contextWindow * OBSERVER_CHUNK_CONTEXT_RATIO),
+		);
+	}
+	return OBSERVER_CHUNK_FALLBACK_MAX_TOKENS;
+}
 
 const SETTINGS_KEY = "observational-memory";
 const PASSIVE_ENV = "PI_OBSERVATIONAL_MEMORY_PASSIVE";
@@ -134,10 +193,12 @@ function normalizeSettingsConfig(value: Record<string, unknown>): Partial<Config
 	const numberKeys = [
 		"observeAfterTokens",
 		"reflectAfterTokens",
+		"observerChunkMaxTokens",
 		"compactAfterTokens",
 		"observationsPoolMaxTokens",
 		"observationsPoolTargetTokens",
 		"agentMaxTurns",
+		"agentMaxTokens",
 	] as const;
 	for (const key of numberKeys) {
 		const normalizedValue = positiveIntegerOrUndefined(value[key]);
@@ -148,6 +209,7 @@ function normalizeSettingsConfig(value: Record<string, unknown>): Partial<Config
 	}
 	const ratio = validRatioOrUndefined(value.compactAfterTokensRatio);
 	if (ratio !== undefined) normalized.compactAfterTokensRatio = ratio;
+	if (typeof value.showWorkerNotifications === "boolean") normalized.showWorkerNotifications = value.showWorkerNotifications;
 	if (typeof value.passive === "boolean") normalized.passive = value.passive;
 	if (typeof value.debugLog === "boolean") normalized.debugLog = value.debugLog;
 	const model = normalizeModel(value.model);

package/src/hooks/compaction-hook.ts

@@ -1,4 +1,8 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	SessionBeforeCompactEvent,
+} from "@earendil-works/pi-coding-agent";
 
 import type { Runtime } from "../runtime.js";
 import { buildCompactionProjection, renderSummary, type Entry } from "../session-ledger/index.js";
@@ -13,7 +17,7 @@ function observationsPoolMaxTokens(runtime: Runtime): number {
 }
 
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
-	pi.on("session_before_compact", async (event: any, ctx: any) => {
+	pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
 		if (runtime.compactHookInFlight) {
 			if (ctx.hasUI) {
 				ctx.ui.notify(
@@ -35,6 +39,10 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 				{ observationsPoolMaxTokens: observationsPoolMaxTokens(runtime) },
 			);
 			const summary = renderSummary(projection.reflections, projection.observations);
+			if (summary.length === 0) {
+				// Decline ownership so Pi's native summarizer preserves the pre-cut context.
+				return;
+			}
 
 			return {
 				compaction: {