@raquezha/noheadroom 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 > **Reclaim your Pi context window.** A local-first context compression bridge for the Pi Coding Agent, powered by [Headroom](https://github.com/headroom-ai/headroom).
 
-`noheadroom` sits between Pi and your LLM, shrinking massive tool results and logs before they reach the model. Save tokens, keep more history, and prevent context-overflow in long sessions.
+`noheadroom` sits between Pi and your LLM, using Headroom to shrink massive tool outputs/results and logs before they become model input. Headroom itself is a general prompt/context compression engine that can transform broader request material. `noheadroom` deliberately applies a stricter Pi policy: user prompts and assistant messages may be sent as context for the compression request, but Pi only accepts mutations to `toolResult` content. User chat, assistant text, tool-call metadata, and tool IDs remain unchanged in real Pi history. Save tokens, keep more history, and prevent context-overflow in long sessions.
 
 ## 🚀 Why noheadroom?
 
@@ -17,7 +17,10 @@ Upstream Headroom protects common agent tool names like `read` and `bash` by def
 
 ## ✨ Features
 
+- **Headroom Bridge, Pi Policy**: Headroom can optimize broad prompt/context payloads; `noheadroom` intentionally narrows what gets applied back to Pi so only `toolResult` content mutates.
 - **Adaptive Payload Sanitization**: renames tool calls during compression to ensure Headroom actually shrinks them.
+- **Strict Candidate Isolation**: limits applied mutations strictly to `toolResult` messages, safely ignoring upstream proxy mangling of user/assistant history to prevent false-positive guard skips.
+- **Turn-by-Turn Loop Prevention**: caches eligible `toolResult` candidate fingerprints using tool identity, content shape, length, and stable content hashes to block useless proxy retries across new conversational turns while still retrying when actual tool output changes.
 - **Pi-Native Metadata Preservation**: original tool IDs and names are never modified in your real session.
 - **Deep Visibility**: compression results appear in your terminal, the Pi footer, and as persistent entries in your session history.
 - **Docker-First Architecture**: designed to work seamlessly with a local containerized backend.

package/dist/bridge.js

@@ -8,10 +8,14 @@ export function buildCompressionPayload(messages, minMessageChars) {
         if (!converted)
             continue;
         const originalText = extractOpenAIText(converted);
-        // Allow any toolResult to be a candidate for compression if Headroom decides to shrink it.
-        // The minMessageChars threshold is primarily to avoid overhead for tiny messages,
-        // but we shouldn't block Headroom if it finds savings in slightly smaller ones.
-        const applyTo = source.role === "toolResult" ? "toolResult" : null;
+        // Mark candidates for compression.
+        // ONLY toolResults are candidates, preserving original Pi conversation fidelity.
+        let applyTo = source.role === "toolResult" ? "toolResult" : null;
+        // Headroom Bypass Rules (Android Hat)
+        // We never want to compress `android layout` JSON dumps or critical adb dumps.
+        if (source.role === "toolResult" && originalText.trim().startsWith("[") && originalText.includes('"resource-id"')) {
+            applyTo = null;
+        }
         if (applyTo && originalText.length >= minMessageChars)
             candidateCount++;
         mappings.push({ sourceIndex, message: converted, applyTo, originalText });
@@ -31,20 +35,19 @@ export function applyCompressionResult(originalMessages, mappings, compressedMes
     for (let index = 0; index < mappings.length; index++) {
         const mapping = mappings[index];
         const compressed = compressedMessages[index];
+        // We only validate and apply changes to explicit candidates.
+        // Headroom is allowed to mangle non-candidates (like assistant history) in its output,
+        // but we simply ignore those changes and keep the original Pi message intact.
+        if (!mapping.applyTo)
+            continue;
         const validation = validateAlignedMessage(mapping.message, compressed);
         if (!validation.ok)
             return validation;
-        const nextText = extractOpenAIText(compressed);
+        let nextText = extractOpenAIText(compressed);
         if (nextText === mapping.originalText)
             continue;
-        if (mapping.applyTo !== "toolResult") {
-            return { ok: false, reason: `non-candidate-changed:${mapping.message.role}` };
-        }
         const target = nextMessages[mapping.sourceIndex];
-        if (target.role !== "toolResult") {
-            return { ok: false, reason: "source-role-mismatch" };
-        }
-        if (!replaceTextContent(target, nextText)) {
+        if (!hasContent(target) || !replaceTextContent(target, nextText)) {
             return { ok: false, reason: "target-content-unreplaceable" };
         }
         appliedMessages++;
@@ -174,8 +177,22 @@ function replaceTextContent(message, text) {
     }
     if (!Array.isArray(message.content))
         return false;
-    const imageParts = message.content.filter((part) => isImageContent(part));
-    message.content = [{ type: "text", text }, ...imageParts];
+    const nextContent = [];
+    let replacedText = false;
+    for (const part of message.content) {
+        if (isTextContent(part)) {
+            if (!replacedText) {
+                nextContent.push({ type: "text", text });
+                replacedText = true;
+            }
+            continue;
+        }
+        nextContent.push(part);
+    }
+    if (!replacedText && text.length > 0) {
+        nextContent.unshift({ type: "text", text });
+    }
+    message.content = nextContent;
     return true;
 }
 function hasContent(message) {

package/dist/index.d.ts

@@ -11,6 +11,7 @@ interface HeadroomRuntimeState {
     processing: boolean;
     lastInputFingerprint: string | null;
     lastOutputFingerprint: string | null;
+    lastGuardSkipCandidateFingerprint: string | null;
     lastCompressionTime: number;
     stats: HeadroomStats;
 }

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { applyCompressionResult, buildCompressionPayload, convertMessage, extractOpenAIText, } from "./bridge.js";
 import { HeadroomHttpClient } from "./client.js";
@@ -5,6 +6,7 @@ import { isRemoteBlocked, loadHeadroomConfig } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
 const STATUS_KEY = "headroom";
 const SUBCOMMANDS = ["status", "on", "off", "health", "stats"];
+const NOTRACE_TELEMETRY_CHANNEL = "notrace.telemetry.extension";
 const COMPRESSION_ENTRY_TYPE = "noheadroom.compression";
 export default function headroomExtension(pi) {
     registerCompressionRenderer(pi);
@@ -12,10 +14,12 @@ export default function headroomExtension(pi) {
     pi.on("session_start", (_event, ctx) => {
         if (isRemoteBlocked(runtime.config)) {
             runtime.refreshStatus(ctx);
+            emitNotraceTelemetry(runtime);
             ctx.ui.notify(`Headroom remote URL is blocked by default: ${runtime.config.baseUrl}\nSet PI_HEADROOM_ALLOW_REMOTE=1 only if you trust that proxy with full context.`, "warning");
             return;
         }
         runtime.refreshStatus(ctx);
+        emitNotraceTelemetry(runtime);
         if (!runtime.state.enabled)
             return;
         void ensureProxyInBackground(runtime, ctx);
@@ -52,6 +56,7 @@ function createRuntime(pi) {
         processing: false,
         lastInputFingerprint: null,
         lastOutputFingerprint: null,
+        lastGuardSkipCandidateFingerprint: null,
         lastCompressionTime: 0,
         stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
     };
@@ -195,6 +200,12 @@ async function handleContextCompression(runtime, event, ctx) {
     const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
     if (payload.candidateCount === 0)
         return undefined;
+    // 3. If eligible candidates haven't changed since the last skip/no-savings result,
+    // don't spend another proxy call just because surrounding conversation changed.
+    const candidateFingerprint = generateCandidateFingerprint(event.messages, payload);
+    if (runtime.state.lastGuardSkipCandidateFingerprint === candidateFingerprint) {
+        return undefined;
+    }
     if (runtime.state.proxyOnline !== true) {
         void ensureProxyInBackground(runtime, ctx);
         return undefined;
@@ -206,8 +217,10 @@ async function handleContextCompression(runtime, event, ctx) {
         const result = await runtime.client.compress(payload.messages, ctx.model?.id, ctx.signal);
         runtime.state.proxyOnline = true;
         if (!result.compressed || result.tokensSaved <= 0) {
-            // Even if no tokens saved, record the input so we don't keep trying
+            // Even if no tokens saved, record fingerprints so we don't keep trying
+            // until the actual compressible candidate material changes.
             runtime.state.lastInputFingerprint = inputFingerprint;
+            runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
             runtime.refreshStatus(ctx);
             return undefined;
         }
@@ -215,7 +228,12 @@ async function handleContextCompression(runtime, event, ctx) {
             minMessageChars: runtime.config.minMessageChars,
         });
         if (!applied.ok) {
+            // Record the input even on guard skips to prevent looping retries for this context
+            runtime.state.lastInputFingerprint = inputFingerprint;
+            runtime.state.lastOutputFingerprint = null;
+            runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
             recordGuardSkip(runtime.state.stats, applied.reason);
+            emitNotraceTelemetry(runtime);
             announceGuardSkip(ctx, applied.reason, result);
             runtime.refreshStatus(ctx);
             return undefined;
@@ -223,7 +241,9 @@ async function handleContextCompression(runtime, event, ctx) {
         // Store fingerprints to break the feedback loop
         runtime.state.lastInputFingerprint = inputFingerprint;
         runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
+        runtime.state.lastGuardSkipCandidateFingerprint = null;
         recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+        emitNotraceTelemetry(runtime);
         announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages);
         runtime.refreshStatus(ctx);
         return { messages: applied.messages };
@@ -236,6 +256,39 @@ async function handleContextCompression(runtime, event, ctx) {
         runtime.state.processing = false;
     }
 }
+function generateCandidateFingerprint(messages, payload) {
+    const units = payload.mappings
+        .filter((mapping) => mapping.applyTo)
+        .map((mapping) => {
+        const source = messages[mapping.sourceIndex];
+        return {
+            applyTo: mapping.applyTo,
+            sourceIndex: mapping.sourceIndex,
+            role: source.role,
+            toolCallId: typeof source.toolCallId === "string" ? source.toolCallId : null,
+            toolName: typeof source.toolName === "string" ? source.toolName : null,
+            contentShape: describeContentShape(source.content),
+            textLength: mapping.originalText.length,
+            textHash: stableHash(mapping.originalText),
+        };
+    });
+    return stableHash(JSON.stringify(units));
+}
+function describeContentShape(content) {
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (!part || typeof part !== "object" || !("type" in part))
+                return "unknown";
+            return String(part.type ?? "unknown");
+        })
+            .join(",");
+    }
+    return typeof content;
+}
+function stableHash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
 function generateFingerprint(messages) {
     return messages
         .map((m) => {
@@ -270,6 +323,57 @@ function recordAppliedCompression(stats, result, appliedMessages) {
     stats.lastSkipReason = undefined;
     stats.last = { ...result, appliedMessages };
 }
+function summarizeTelemetry(state) {
+    if (state.stats.last) {
+        const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
+        return `compressed ${state.stats.last.tokensBefore.toLocaleString()} to ${state.stats.last.tokensAfter.toLocaleString()} tokens; saved ${state.stats.last.tokensSaved.toLocaleString()} tokens across ${state.stats.last.appliedMessages} tool results (-${pct}%)`;
+    }
+    if (!state.enabled)
+        return "headroom loaded but disabled for this session";
+    if (state.stats.lastSkipReason)
+        return `compression not applied; last guard skip: ${state.stats.lastSkipReason}`;
+    if (state.stats.lastError)
+        return `compression unavailable; last error: ${state.stats.lastError}`;
+    if (state.proxyOnline === false)
+        return "proxy unavailable";
+    if (state.proxyStarting)
+        return "proxy starting";
+    return "headroom loaded; no compression applied yet";
+}
+function emitNotraceTelemetry(runtime) {
+    const state = runtime.state;
+    const status = !state.enabled
+        ? "loaded-disabled"
+        : state.stats.last
+            ? "active"
+            : "loaded-inactive";
+    const details = {
+        attempts: state.stats.attempts,
+        applied: state.stats.applied,
+        guardSkips: state.stats.guardSkips,
+        tokensSaved: state.stats.tokensSaved,
+        proxyOnline: state.proxyOnline,
+        proxyStarting: state.proxyStarting,
+        lastSkipReason: state.stats.lastSkipReason,
+        lastError: state.stats.lastError,
+    };
+    if (state.stats.last)
+        details.last = { ...state.stats.last };
+    try {
+        runtime.pi.events.emit(NOTRACE_TELEMETRY_CHANNEL, {
+            extension: "noheadroom",
+            loaded: true,
+            enabled: state.enabled,
+            active: Boolean(state.stats.last),
+            status,
+            summary: summarizeTelemetry(state),
+            details,
+        });
+    }
+    catch {
+        // Telemetry should never break compression behavior.
+    }
+}
 function announceAppliedCompression(pi, ctx, result, appliedMessages) {
     const pct = Math.round((1 - result.compressionRatio) * 100);
     const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
@@ -288,6 +392,7 @@ function announceGuardSkip(ctx, reason, result) {
 function recordCompressionError(runtime, ctx, error) {
     runtime.state.stats.lastError = getErrorMessage(error);
     if (isAbortOrTimeoutError(error)) {
+        emitNotraceTelemetry(runtime);
         runtime.refreshStatus(ctx);
         return;
     }
@@ -296,6 +401,7 @@ function recordCompressionError(runtime, ctx, error) {
         runtime.state.offlineWarningShown = true;
         ctx.ui.notify(`Headroom proxy unavailable. Compression disabled until /headroom health succeeds.\n${runtime.state.stats.lastError}`, "warning");
     }
+    emitNotraceTelemetry(runtime);
     runtime.refreshStatus(ctx);
 }
 function getErrorMessage(error) {
@@ -319,6 +425,7 @@ async function handleCommand(runtime, command, ctx) {
         runtime.state.offlineWarningShown = false;
         runtime.state.proxyStartAttempted = false;
         const healthy = await runtime.ensureProxy(ctx);
+        emitNotraceTelemetry(runtime);
         ctx.ui.notify(healthy
             ? "Headroom compression enabled. Proxy will keep running after Pi exits."
             : proxyStartHint(runtime.config), healthy ? "info" : "warning");
@@ -326,6 +433,7 @@ async function handleCommand(runtime, command, ctx) {
     }
     if (command === "off") {
         runtime.state.enabled = false;
+        emitNotraceTelemetry(runtime);
         runtime.refreshStatus(ctx);
         ctx.ui.notify("Headroom compression disabled for this Pi session. The proxy process is left running.", "info");
         return;
@@ -333,6 +441,7 @@ async function handleCommand(runtime, command, ctx) {
     if (command === "health") {
         runtime.state.proxyStartAttempted = false;
         const healthy = await runtime.ensureProxy(ctx);
+        emitNotraceTelemetry(runtime);
         ctx.ui.notify(healthy ? `Headroom proxy online: ${runtime.config.baseUrl}` : proxyStartHint(runtime.config), healthy ? "info" : "warning");
         return;
     }

package/extensions/bridge.ts

@@ -28,10 +28,16 @@ export function buildCompressionPayload(messages: AgentMessage[], minMessageChar
 		if (!converted) continue;
 
 		const originalText = extractOpenAIText(converted);
-		// Allow any toolResult to be a candidate for compression if Headroom decides to shrink it.
-		// The minMessageChars threshold is primarily to avoid overhead for tiny messages,
-		// but we shouldn't block Headroom if it finds savings in slightly smaller ones.
-		const applyTo = source.role === "toolResult" ? "toolResult" : null;
+		// Mark candidates for compression.
+		// ONLY toolResults are candidates, preserving original Pi conversation fidelity.
+		let applyTo: "toolResult" | null = source.role === "toolResult" ? "toolResult" : null;
+
+		// Headroom Bypass Rules (Android Hat)
+		// We never want to compress `android layout` JSON dumps or critical adb dumps.
+		if (source.role === "toolResult" && originalText.trim().startsWith("[") && originalText.includes('"resource-id"')) {
+			applyTo = null;
+		}
+		
 		if (applyTo && originalText.length >= minMessageChars) candidateCount++;
 		mappings.push({ sourceIndex, message: converted, applyTo, originalText });
 	}
@@ -59,22 +65,20 @@ export function applyCompressionResult(
 	for (let index = 0; index < mappings.length; index++) {
 		const mapping = mappings[index];
 		const compressed = compressedMessages[index];
+
+		// We only validate and apply changes to explicit candidates.
+		// Headroom is allowed to mangle non-candidates (like assistant history) in its output,
+		// but we simply ignore those changes and keep the original Pi message intact.
+		if (!mapping.applyTo) continue;
+
 		const validation = validateAlignedMessage(mapping.message, compressed);
 		if (!validation.ok) return validation;
 
-		const nextText = extractOpenAIText(compressed);
+		let nextText = extractOpenAIText(compressed);
 		if (nextText === mapping.originalText) continue;
 
-		if (mapping.applyTo !== "toolResult") {
-			return { ok: false, reason: `non-candidate-changed:${mapping.message.role}` };
-		}
-
 		const target = nextMessages[mapping.sourceIndex] as AnyMessage;
-		if (target.role !== "toolResult") {
-			return { ok: false, reason: "source-role-mismatch" };
-		}
-
-		if (!replaceTextContent(target, nextText)) {
+		if (!hasContent(target) || !replaceTextContent(target, nextText)) {
 			return { ok: false, reason: "target-content-unreplaceable" };
 		}
 		appliedMessages++;
@@ -204,8 +208,26 @@ function replaceTextContent(message: MessageWithContent, text: string): boolean
 		return true;
 	}
 	if (!Array.isArray(message.content)) return false;
-	const imageParts = message.content.filter((part): part is ImageContent => isImageContent(part));
-	message.content = [{ type: "text", text }, ...imageParts];
+
+	const nextContent: unknown[] = [];
+	let replacedText = false;
+
+	for (const part of message.content) {
+		if (isTextContent(part)) {
+			if (!replacedText) {
+				nextContent.push({ type: "text", text });
+				replacedText = true;
+			}
+			continue;
+		}
+		nextContent.push(part);
+	}
+
+	if (!replacedText && text.length > 0) {
+		nextContent.unshift({ type: "text", text });
+	}
+
+	message.content = nextContent as typeof message.content;
 	return true;
 }
 

package/extensions/index.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { ContextEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import {
@@ -9,10 +10,11 @@ import {
 import { HeadroomHttpClient } from "./client.js";
 import { isRemoteBlocked, loadHeadroomConfig } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
-import type { AgentMessage, CompressResult, HeadroomConfig, HeadroomStats } from "./types.js";
+import type { AgentMessage, CompressResult, CompressionPayload, HeadroomConfig, HeadroomStats } from "./types.js";
 
 const STATUS_KEY = "headroom";
 const SUBCOMMANDS = ["status", "on", "off", "health", "stats"] as const;
+const NOTRACE_TELEMETRY_CHANNEL = "notrace.telemetry.extension";
 
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
@@ -26,6 +28,7 @@ interface HeadroomRuntimeState {
 	processing: boolean;
 	lastInputFingerprint: string | null;
 	lastOutputFingerprint: string | null;
+	lastGuardSkipCandidateFingerprint: string | null;
 	lastCompressionTime: number;
 	stats: HeadroomStats;
 }
@@ -59,6 +62,7 @@ export default function headroomExtension(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
 		if (isRemoteBlocked(runtime.config)) {
 			runtime.refreshStatus(ctx);
+			emitNotraceTelemetry(runtime);
 			ctx.ui.notify(
 				`Headroom remote URL is blocked by default: ${runtime.config.baseUrl}\nSet PI_HEADROOM_ALLOW_REMOTE=1 only if you trust that proxy with full context.`,
 				"warning",
@@ -66,6 +70,7 @@ export default function headroomExtension(pi: ExtensionAPI) {
 			return;
 		}
 		runtime.refreshStatus(ctx);
+		emitNotraceTelemetry(runtime);
 		if (!runtime.state.enabled) return;
 		void ensureProxyInBackground(runtime, ctx);
 	});
@@ -105,6 +110,7 @@ function createRuntime(pi: ExtensionAPI): HeadroomRuntime {
 		processing: false,
 		lastInputFingerprint: null,
 		lastOutputFingerprint: null,
+		lastGuardSkipCandidateFingerprint: null,
 		lastCompressionTime: 0,
 		stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
 	};
@@ -258,6 +264,13 @@ async function handleContextCompression(
 	if (shouldSkipBeforePayload(runtime, ctx)) return undefined;
 	const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
 	if (payload.candidateCount === 0) return undefined;
+
+	// 3. If eligible candidates haven't changed since the last skip/no-savings result,
+	// don't spend another proxy call just because surrounding conversation changed.
+	const candidateFingerprint = generateCandidateFingerprint(event.messages, payload);
+	if (runtime.state.lastGuardSkipCandidateFingerprint === candidateFingerprint) {
+		return undefined;
+	}
 	if (runtime.state.proxyOnline !== true) {
 		void ensureProxyInBackground(runtime, ctx);
 		return undefined;
@@ -270,8 +283,10 @@ async function handleContextCompression(
 		const result = await runtime.client.compress(payload.messages, ctx.model?.id, ctx.signal);
 		runtime.state.proxyOnline = true;
 		if (!result.compressed || result.tokensSaved <= 0) {
-			// Even if no tokens saved, record the input so we don't keep trying
+			// Even if no tokens saved, record fingerprints so we don't keep trying
+			// until the actual compressible candidate material changes.
 			runtime.state.lastInputFingerprint = inputFingerprint;
+			runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
 			runtime.refreshStatus(ctx);
 			return undefined;
 		}
@@ -280,7 +295,13 @@ async function handleContextCompression(
 			minMessageChars: runtime.config.minMessageChars,
 		});
 		if (!applied.ok) {
+			// Record the input even on guard skips to prevent looping retries for this context
+			runtime.state.lastInputFingerprint = inputFingerprint;
+			runtime.state.lastOutputFingerprint = null;
+			runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
+
 			recordGuardSkip(runtime.state.stats, applied.reason);
+			emitNotraceTelemetry(runtime);
 			announceGuardSkip(ctx, applied.reason, result);
 			runtime.refreshStatus(ctx);
 			return undefined;
@@ -289,8 +310,10 @@ async function handleContextCompression(
 		// Store fingerprints to break the feedback loop
 		runtime.state.lastInputFingerprint = inputFingerprint;
 		runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
+		runtime.state.lastGuardSkipCandidateFingerprint = null;
 
 		recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+		emitNotraceTelemetry(runtime);
 		announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages);
 		runtime.refreshStatus(ctx);
 		return { messages: applied.messages };
@@ -302,6 +325,45 @@ async function handleContextCompression(
 	}
 }
 
+function generateCandidateFingerprint(messages: AgentMessage[], payload: CompressionPayload): string {
+	const units = payload.mappings
+		.filter((mapping) => mapping.applyTo)
+		.map((mapping) => {
+			const source = messages[mapping.sourceIndex] as AgentMessage & {
+				content?: unknown;
+				toolCallId?: unknown;
+				toolName?: unknown;
+			};
+			return {
+				applyTo: mapping.applyTo,
+				sourceIndex: mapping.sourceIndex,
+				role: source.role,
+				toolCallId: typeof source.toolCallId === "string" ? source.toolCallId : null,
+				toolName: typeof source.toolName === "string" ? source.toolName : null,
+				contentShape: describeContentShape(source.content),
+				textLength: mapping.originalText.length,
+				textHash: stableHash(mapping.originalText),
+			};
+		});
+	return stableHash(JSON.stringify(units));
+}
+
+function describeContentShape(content: unknown): string {
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => {
+				if (!part || typeof part !== "object" || !("type" in part)) return "unknown";
+				return String((part as { type?: unknown }).type ?? "unknown");
+			})
+			.join(",");
+	}
+	return typeof content;
+}
+
+function stableHash(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
 function generateFingerprint(messages: AgentMessage[]): string {
 	return messages
 		.map((m) => {
@@ -339,6 +401,52 @@ function recordAppliedCompression(stats: HeadroomStats, result: CompressResult,
 	stats.last = { ...result, appliedMessages };
 }
 
+function summarizeTelemetry(state: HeadroomRuntimeState): string | null {
+	if (state.stats.last) {
+		const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
+		return `compressed ${state.stats.last.tokensBefore.toLocaleString()} to ${state.stats.last.tokensAfter.toLocaleString()} tokens; saved ${state.stats.last.tokensSaved.toLocaleString()} tokens across ${state.stats.last.appliedMessages} tool results (-${pct}%)`;
+	}
+	if (!state.enabled) return "headroom loaded but disabled for this session";
+	if (state.stats.lastSkipReason) return `compression not applied; last guard skip: ${state.stats.lastSkipReason}`;
+	if (state.stats.lastError) return `compression unavailable; last error: ${state.stats.lastError}`;
+	if (state.proxyOnline === false) return "proxy unavailable";
+	if (state.proxyStarting) return "proxy starting";
+	return "headroom loaded; no compression applied yet";
+}
+
+function emitNotraceTelemetry(runtime: HeadroomRuntime): void {
+	const state = runtime.state;
+	const status = !state.enabled
+		? "loaded-disabled"
+		: state.stats.last
+			? "active"
+			: "loaded-inactive";
+	const details: Record<string, unknown> = {
+		attempts: state.stats.attempts,
+		applied: state.stats.applied,
+		guardSkips: state.stats.guardSkips,
+		tokensSaved: state.stats.tokensSaved,
+		proxyOnline: state.proxyOnline,
+		proxyStarting: state.proxyStarting,
+		lastSkipReason: state.stats.lastSkipReason,
+		lastError: state.stats.lastError,
+	};
+	if (state.stats.last) details.last = { ...state.stats.last };
+	try {
+		runtime.pi.events.emit(NOTRACE_TELEMETRY_CHANNEL, {
+			extension: "noheadroom",
+			loaded: true,
+			enabled: state.enabled,
+			active: Boolean(state.stats.last),
+			status,
+			summary: summarizeTelemetry(state),
+			details,
+		});
+	} catch {
+		// Telemetry should never break compression behavior.
+	}
+}
+
 function announceAppliedCompression(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -364,6 +472,7 @@ function announceGuardSkip(ctx: ExtensionContext, reason: string, result: Compre
 function recordCompressionError(runtime: HeadroomRuntime, ctx: ExtensionContext, error: unknown): void {
 	runtime.state.stats.lastError = getErrorMessage(error);
 	if (isAbortOrTimeoutError(error)) {
+		emitNotraceTelemetry(runtime);
 		runtime.refreshStatus(ctx);
 		return;
 	}
@@ -376,6 +485,7 @@ function recordCompressionError(runtime: HeadroomRuntime, ctx: ExtensionContext,
 			"warning",
 		);
 	}
+	emitNotraceTelemetry(runtime);
 	runtime.refreshStatus(ctx);
 }
 
@@ -402,6 +512,7 @@ async function handleCommand(runtime: HeadroomRuntime, command: Subcommand, ctx:
 		runtime.state.offlineWarningShown = false;
 		runtime.state.proxyStartAttempted = false;
 		const healthy = await runtime.ensureProxy(ctx);
+		emitNotraceTelemetry(runtime);
 		ctx.ui.notify(
 			healthy
 				? "Headroom compression enabled. Proxy will keep running after Pi exits."
@@ -412,6 +523,7 @@ async function handleCommand(runtime: HeadroomRuntime, command: Subcommand, ctx:
 	}
 	if (command === "off") {
 		runtime.state.enabled = false;
+		emitNotraceTelemetry(runtime);
 		runtime.refreshStatus(ctx);
 		ctx.ui.notify("Headroom compression disabled for this Pi session. The proxy process is left running.", "info");
 		return;
@@ -419,6 +531,7 @@ async function handleCommand(runtime: HeadroomRuntime, command: Subcommand, ctx:
 	if (command === "health") {
 		runtime.state.proxyStartAttempted = false;
 		const healthy = await runtime.ensureProxy(ctx);
+		emitNotraceTelemetry(runtime);
 		ctx.ui.notify(
 			healthy ? `Headroom proxy online: ${runtime.config.baseUrl}` : proxyStartHint(runtime.config),
 			healthy ? "info" : "warning",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/noheadroom",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Personal Headroom compression bridge for Pi with Docker-first defaults and Pi tool-name adaptation",
   "main": "dist/index.js",
   "type": "module",