pi-mega-compact 0.13.0 → 0.13.2

package/extensions/mega-events/agent-handlers/agentEndHandler.ts

@@ -0,0 +1,238 @@
+/**
+ * agent-handlers/agentEndHandler.ts — the pi `agent_end` handler body.
+ *
+ * Extracted from agent-handlers.ts (delegate-shell split) to keep every source
+ * file under the extensions limit. Contains the live-agent status-line updates,
+ * the S16/S38.5 mid-run durable trim (race-guarded, deferred ctx.compact), the
+ * S28 length-stop nudge, and the R4-R11 error-retry safety net.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import { piCompactWouldNoop } from "../../mega-pipeline.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { safeSendUserMessage } from "../send-safe.js";
+
+/** Handle the `agent_end` pi event. Non-fatal end-to-end. */
+export async function handleAgentEnd(
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): Promise<void> {
+	runtime.activeAgents = Math.max(0, runtime.activeAgents - 1);
+	runtime.dashboard.event("agent_end", {
+		activeAgents: runtime.activeAgents,
+	});
+	if (runtime.activeAgents > 0) {
+		runtime.setStatus(
+			ctx,
+			`mega-compact: ▶ ${runtime.activeAgents} agent${runtime.activeAgents === 1 ? "" : "s"}`,
+		);
+	} else {
+		runtime.setStatus(
+			ctx,
+			config.auto ? "mega-compact: ready" : "mega-compact: manual only",
+		);
+	}
+	// S16 continuation fallback: if the turn settled idle right after a live-trim
+	// compaction AND there is queued work AND we haven't nudged recently, nudge
+	// once so the agent continues (the live trim should make this rare). Guarded
+	// to never busy-loop: one nudge per 30s, only when truly idle + queued.
+	if (
+		(config.auto || config.autoContinueLengthStop) &&
+		runtime.activeAgents === 0
+	) {
+		try {
+			const idle = ctx.isIdle?.() ?? true;
+			const queued = ctx.hasPendingMessages?.() ?? false;
+			const now = Date.now();
+			// S38.5: read LIVE pressure from ctx.getContextUsage() instead of the
+			// stale runtime.lastCtxTokens (only updated by the `context` event).
+			// agent_end may fire without a preceding context event this turn (e.g.
+			// a sub-agent settling), so the cached value can be null/stale and the
+			// durable-trim branch would be unreachable. ctx.getContextUsage() is the
+			// authoritative live reading (mirrors context-handler.ts:86). Fall back
+			// to the cached value only if the ctx omits it.
+			const liveUsage = ctx.getContextUsage?.();
+			const liveTokens =
+				typeof liveUsage?.tokens === "number"
+					? liveUsage.tokens
+					: (runtime.lastCtxTokens ?? 0);
+			// Keep the cache fresh for snapshot()/diag regardless of which source we use.
+			if (typeof liveUsage?.tokens === "number") {
+				runtime.lastCtxTokens = liveUsage.tokens;
+			}
+			if (typeof liveUsage?.percent === "number") {
+				runtime.lastCtxPercent = liveUsage.percent;
+			}
+			if (typeof liveUsage?.contextWindow === "number") {
+				runtime.lastCtxWindow = liveUsage.contextWindow;
+			}
+			// DIAG (team-run relief): surface whether the agent is idle + over
+			// threshold at agent_end so we can see if a mid-run durable-trim trigger
+			// *should* have fired but didn't.
+			const overThreshold = liveTokens >= runtime.effectiveThreshold;
+			runtime.diagAgentEndIdle++;
+			runtime.logger.info("agent-end-idle", {
+				sessionId: runtime.rt.sessionId,
+				idle,
+				queued,
+				overThreshold,
+				ctxPct: runtime.lastCtxPercent,
+				ctxTokens: runtime.lastCtxTokens,
+				thresholdTokens: config.thresholdTokens,
+				wouldNudge:
+					idle &&
+					(queued || overThreshold) &&
+					now >= runtime.resumeNudgeUntil,
+			});
+			// S16+S24: MID-RUN DURABLE TRIM. During a long team run (sub-agents),
+			// pi's native durable compaction only fires from _checkCompaction at
+			// PARENT settle (agent-session.js:760/844), so the on-disk transcript +
+			// context meter balloon to ~150k and never relieve until the very end
+			// ("compacts but doesn't resume"). agent_end with activeAgents===0 is a
+			// SAFE, settled point: calling ctx.compact() here does NOT abort an
+			// in-flight turn (the S16 danger is only mid-turn). ctx.compact() runs
+			// pi's flow, which fires our session_before_compact handler to supply
+			// the durable trim (truncates the transcript from firstKeptEntryId).
+			// Guarded three ways: only when truly idle + over threshold, only when
+			// pi would actually compact (piCompactWouldNoop skips the user-facing
+			// no-op throw), and debounced (one durable trim per 2s) to avoid
+			// thrashing the transcript while sub-agents keep settling.
+			//
+			// FIX "compacts but doesn't resume": the manual ctx.compact() path
+			// STOPS the agent loop (agent-session.js:1345). The old resume-nudge
+			// was gated on `queued`, so when a sub-agent settled with no
+			// *immediately* queued message, the trim fired but the nudge did not,
+			// and the (stopped) session hung. The trim still fires on
+			// `idle && overThreshold` — we intentionally do NOT add a `!queued`
+			// guard, because that would suppress mid-run relief exactly during
+			// team-run waves where queued is usually true and relief is needed
+			// most. Instead we DECOUPLE the nudge from `queued`: after a durable
+			// trim we ALWAYS nudge so the agent reliably restarts. Debounced 30s.
+			let didDurableTrim = false;
+			if (
+				config.auto &&
+				idle &&
+				overThreshold &&
+				now >= runtime.debounceUntil
+			) {
+				// COMPACT-DEDUP FIX: skip the manual durable-trim trigger when pi's
+				// NATIVE auto-compaction just fired (or is in-flight). pi emits
+				// agent_end BEFORE its own _checkCompaction (per its docstring:
+				// "Called after agent_end and before prompt submission"), so a
+				// synchronous `piCompactWouldNoop` branch check misses a native
+				// compaction that hasn't appended its entry yet — calling
+				// ctx.compact() then races with pi and throws "Already compacted"
+				// to the user. The `lastNativeCompactAt` cooldown (updated by the
+				// session_compact listener for EVERY compaction, native or
+				// extension-supplied) closes that race window.
+				//
+				// S38.5: strict race guard widens the cooldown 10s -> 30s AND defers
+				// ctx.compact() via setTimeout(500) with a re-check, so pi's
+				// about-to-run native _checkCompaction can append its `compaction`
+				// branch entry first (closes the first-race-in-burst window). Gated
+				// by MEGACOMPACT_RACE_GUARD_STRICT (default true); false reverts to
+				// the v0.7.4 synchronous 10s guard. Mirrors the legacy path in
+				// context-handler.ts:258-287 so both call sites stay in sync.
+				const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
+				const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+				// CRITICAL-OVER ESCAPE HATCH: when context is critically over the
+				// window (>= 90%), force the durable ctx.compact() even if
+				// piCompactWouldNoop says it would no-op ("Already compacted").
+				// Without this, the on-disk transcript never truncates and the
+				// session stays overflowed on every resume — the "Already
+				// compacted" + overflow death-spiral (2026-08-01 incident). The
+				// cooldown still applies (we don't spam compact), but the no-op
+				// gate is bypassed when critical. pi's ctx.compact() may throw
+				// "Already compacted" in the truly-no-op case — wrapped in
+				// try/catch so the throw is non-fatal.
+				const criticalOver = (runtime.lastCtxPercent ?? 0) >= 90;
+				if (sinceCompact < cooldownMs) {
+					runtime.diagAgentEndDurableSkipRecent++;
+				} else if (criticalOver || !piCompactWouldNoop(ctx)) {
+					runtime.debounceUntil = now + 2000;
+					runtime.diagAgentEndDurable++;
+					runtime.logger.info("agent-end-durable-trigger", {
+						sessionId: runtime.rt.sessionId,
+						ctxTokens: runtime.lastCtxTokens,
+						thresholdTokens: config.thresholdTokens,
+						queued,
+					});
+					if (config.raceGuardStrict) {
+						// Strict: defer ctx.compact() with a re-check so pi's
+						// about-to-run native _checkCompaction can append its
+						// `compaction` branch entry first. setTimeout(500) — pi's
+						// compaction-summary append is async I/O, so queueMicrotask
+						// would re-check before it lands.
+						const stamp = runtime.rt.lastNativeCompactAt;
+						const liveSid = runtime.rt.sessionId;
+						const liveCritical = criticalOver;
+						setTimeout(() => {
+							try {
+								if (runtime.rt.sessionId !== liveSid) return; // session reset
+								// IMPORTANT: recompute Date.now() inside the timeout.
+								// `now` above is the durable-trim handler's timestamp and can be
+								// ~500ms stale by the time this callback runs.
+								const since2 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+								if (
+									runtime.rt.lastNativeCompactAt !== stamp &&
+									since2 < cooldownMs
+								)
+									return;
+								// CRITICAL-OVER ESCAPE HATCH: bypass the no-op gate when
+								// critical (captured at handler time) so the durable trim fires.
+								if (!liveCritical && piCompactWouldNoop(ctx)) return;
+								ctx.compact({
+									customInstructions: undefined,
+								}); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. May throw "Already compacted" when the escape hatch forces it — caught below.
+							} catch {
+								/* non-fatal: "Already compacted" throws are expected when the critical-over hatch forces a no-op compact */
+							}
+						}, 500);
+					} else {
+						try {
+							ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. May throw "Already compacted" when the critical-over escape hatch forces it — caught.
+						} catch {
+							/* non-fatal */
+						}
+					}
+					didDurableTrim = true;
+				}
+			}
+			// Restart the agent after a mid-run durable trim (which stopped it), or
+			// when it settled idle with queued work. Decoupled from `queued` for the
+			// durable-trim case — see FIX note above. Debounced 30s; never blocks.
+			const lengthStop =
+				config.autoContinueLengthStop && runtime.rt.lengthStopPending;
+			if (
+				idle &&
+				now >= runtime.resumeNudgeUntil &&
+				((config.auto && (didDurableTrim || queued)) || lengthStop)
+			) {
+				runtime.resumeNudgeUntil = now + 30_000;
+				if (runtime.rt.lengthStopPending) {
+					runtime.rt.lengthStopPending = false; // one-shot: never re-fire for same stop
+					runtime.dashboard.event("length_stop_continue", {
+						turnIndex: runtime.currentTurn,
+					});
+					runtime.logger.info("length_stop_continue", {
+						sessionId: runtime.rt.sessionId,
+						didDurableTrim,
+						queued,
+					});
+				}
+				// S28: when a length-stop (max-output-token truncation) fired WITHOUT a durable trim, do NOT claim a compaction happened
+				// (nothing was compacted on the low-pressure length path). Branch the message so the nudge matches reality.
+				const nudgeMsg =
+					lengthStop && !didDurableTrim
+						? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
+						: "[mega-compact] continue from the compacted context above.";
+				await safeSendUserMessage(pi, nudgeMsg);
+			}
+		} catch {
+			/* non-fatal: a failed nudge never blocks */
+		}
+	}
+	runtime.snapshot(ctx);
+}

package/extensions/mega-events/agent-handlers/turnEndHandler/cacheStripe.ts

@@ -0,0 +1,74 @@
+/**
+ * turnEndHandler/cacheStripe.ts — P3.5 topic-shift stripe refresh.
+ *
+ * Extracted from turnEndHandler.ts (delegate-shell split) to keep every source
+ * file under the extensions limit. When MEGACOMPACT_CACHE_STRIPING is ON, embed
+ * the current turn, detect topic shift vs. the previous turn, and refresh cache
+ * stripe assignments when shifted (or first turn). Best-effort: failures log +
+ * continue, never break the agent loop.
+ */
+import type { MegaRuntime } from "../../../mega-runtime.js";
+import type { MegaConfig } from "../../../mega-config.js";
+import { defaultEmbedder } from "../../../../src/embedder.js";
+import { storeTopicEmbedding, loadTopicEmbedding, detectTopicShift } from "../../separated-prompt.js";
+import { refreshStripeAssignments as writeStripeAssignments } from "../../../../src/cache-stripe-impl.js";
+import type { TurnEndEvent } from "./event.js";
+
+/** P3.5: topic-shift stripe refresh. Best-effort + non-fatal. */
+export function cacheStripe(
+	event: TurnEndEvent,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): void {
+	if (config.cacheStriping) {
+		try {
+			const stateDir = runtime.currentStateDir;
+			const sessionId = runtime.rt.sessionId;
+			const currentTurn = event.turnIndex;
+			const embedder = defaultEmbedder();
+
+			// (a) Extract text from the assistant's response for topic embedding.
+			let textToEmbed = "";
+			const msg = event.message;
+			if (msg.role === "assistant" && Array.isArray(msg.content)) {
+				for (const part of msg.content) {
+					if ("text" in part && typeof part.text === "string") {
+						textToEmbed += part.text + " ";
+					}
+				}
+			}
+			textToEmbed = textToEmbed.trim() || `turn-${currentTurn}`;
+			const embedding = new Float32Array(embedder.embed(textToEmbed));
+			storeTopicEmbedding(stateDir, sessionId, currentTurn, embedding);
+
+			// (b) Load previous turn's embedding and detect topic shift.
+			const prevEmb = currentTurn > 0
+				? loadTopicEmbedding(stateDir, sessionId, currentTurn - 1)
+				: null;
+			const shifted = currentTurn === 0 || detectTopicShift(embedding, prevEmb);
+
+			// (c) If shifted (or first turn), refresh stripe assignments (WRITE path).
+			let chunkCount = 0;
+			if (shifted) {
+				chunkCount = writeStripeAssignments(
+					stateDir,
+					undefined,
+					embedder,
+					(detail) => runtime.logger.info("stripe_refresh_detail", {
+						detail,
+						turnIndex: currentTurn,
+					}),
+				);
+			}
+
+			// (d) Log the refresh outcome.
+			runtime.logger.info("stripe_refresh", {
+				turnIndex: currentTurn,
+				shifted,
+				chunkCount,
+			});
+		} catch {
+			/* non-fatal: stripe refresh never breaks the agent loop */
+		}
+	}
+}

package/extensions/mega-events/agent-handlers/turnEndHandler/contextHealth.ts

@@ -0,0 +1,50 @@
+/**
+ * turnEndHandler/contextHealth.ts — v0.12 context-health mitigation.
+ *
+ * Extracted from turnEndHandler.ts (delegate-shell split) to keep every source
+ * file under the extensions limit. Computes + persists the health score and
+ * acts on mitigation signals (force-compact / prefix-break) here at turn_end,
+ * where ctx is in scope. Non-fatal.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../../mega-runtime.js";
+import { piCompactWouldNoop } from "../../../mega-pipeline.js";
+import type { MegaConfig } from "../../../mega-config.js";
+import { handleTurnEndHealth } from "../../health-handler.js";
+import type { TurnEndEvent } from "./event.js";
+
+/** v0.12: context-health mitigation. Non-fatal end-to-end. */
+export function contextHealth(
+	event: TurnEndEvent,
+	ctx: ExtensionContext,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): void {
+	// v0.12: Context Health — compute + persist health score. Non-fatal.
+	// Mitigation signals are acted on here (ctx is in scope at turn_end).
+	const healthSignal = handleTurnEndHealth(event, runtime, config);
+	if (healthSignal.forceCompact) {
+		runtime.logger?.info("health_mitigate_compact", {
+			composite: healthSignal.composite,
+			turnIndex: event.turnIndex,
+		});
+		try {
+			// Force a compaction to flush degraded context. Same race-guarded
+			// deferred path as the critical-over escape hatch above.
+			if (!piCompactWouldNoop(ctx)) {
+				ctx.compact();
+			}
+		} catch {
+			/* non-fatal: mitigation never breaks the agent loop */
+		}
+	}
+	if (healthSignal.breakPrefix) {
+		runtime.logger?.info("health_mitigate_prefix_break", {
+			turnIndex: event.turnIndex,
+		});
+		// Invalidate the cached trim so the next context event regenerates
+		// from scratch — the prefix change forces a cache miss, bypassing
+		// the corrupted KV state.
+		runtime.trimCache = null;
+	}
+}