@raquezha/noheadroom 0.3.2 → 0.3.4

package/README.md

@@ -1,28 +1,21 @@
 # noheadroom 🗜
 
-> **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).
+> **Reclaim your Pi context window.** A local-first context compression bridge for the Pi Coding Agent, powered by [Headroom](https://github.com/headroomlabs-ai/headroom).
 
 `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?
 
-Upstream Headroom protects common agent tool names like `read` and `bash` by default. In a standard Pi workflow, this means large file reads often bypass compression entirely.
-
-`noheadroom` adapts the compression payload to bypass these exclusions while **fully preserving your Pi session metadata**.
-
-| Setup | Tool Name | Headroom Action | Savings |
-|---|---|---|---|
-| Vanilla | `read` | `excluded_tool` | 0% |
-| **noheadroom** | `read` | `smart_crusher` | **60-90%** |
+Headroom intentionally protects file reads: changing source text can break exact-match edits. `noheadroom` keeps those reads raw and compresses eligible large text-only tool results (for example, repetitive logs). It never changes the stored Pi session transcript.
 
 ## ✨ 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.
+- **Tool Fidelity**: preserves tool names and arguments so Headroom's protected-tool policy remains effective.
+- **Strict Candidate Isolation**: applies only eligible text-only, non-error `toolResult` changes; rejects retrieval markers without a registered retrieval tool.
+- **Request-local Replay**: reuses validated compression for the same tool call and unchanged result on later model requests without re-calling the proxy. A new tool call with the same output remains raw to avoid re-read loops.
 - **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.
+- **Visibility**: session-local compression estimates appear in the terminal and Pi footer; proxy `/stats` does not count extension `/v1/compress` requests as inference savings.
 - **Docker-First Architecture**: designed to work seamlessly with a local containerized backend.
 - **Local-First Privacy**: by default, context never leaves your machine.
 

package/dist/bridge.d.ts

@@ -5,8 +5,7 @@ type AnyMessage = AgentMessage & {
     timestamp?: number;
 };
 export declare function buildCompressionPayload(messages: AgentMessage[], minMessageChars: number): CompressionPayload;
-export declare function applyCompressionResult(originalMessages: AgentMessage[], mappings: CompressionMapping[], compressedMessages: OpenAIMessage[], _options: ApplyCompressionOptions): ApplyCompressionResult;
+export declare function applyCompressionResult(originalMessages: AgentMessage[], mappings: CompressionMapping[], compressedMessages: OpenAIMessage[], options: ApplyCompressionOptions): ApplyCompressionResult;
 export declare function convertMessage(message: AnyMessage): OpenAIMessage | undefined;
 export declare function extractOpenAIText(message: OpenAIMessage): string;
-export declare function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[];
 export {};

package/dist/bridge.js

@@ -1,4 +1,7 @@
 const STANDARD_COMPRESSIBLE_ROLES = new Set(["user", "assistant", "toolResult"]);
+// File reads supply exact edit anchors; directives and recovered evidence must stay raw.
+const PROTECTED_TOOLS = new Set(["read", "read_file", "view", "edit", "write", "skill", "headroom_retrieve"]);
+const CCR_MARKER = /Retrieve\s+(?:more|original):\s*hash=|<<ccr:/i;
 export function buildCompressionPayload(messages, minMessageChars) {
     const mappings = [];
     let candidateCount = 0;
@@ -10,13 +13,19 @@ export function buildCompressionPayload(messages, minMessageChars) {
         const originalText = extractOpenAIText(converted);
         // Mark candidates for compression.
         // ONLY toolResults are candidates, preserving original Pi conversation fidelity.
-        let applyTo = source.role === "toolResult" ? "toolResult" : null;
+        const textOnly = typeof source.content === "string" ||
+            (Array.isArray(source.content) && source.content.every(isTextContent));
+        let applyTo = source.role === "toolResult" &&
+            textOnly && originalText.length >= minMessageChars &&
+            !("isError" in source && source.isError) &&
+            !PROTECTED_TOOLS.has((readStringProperty(source, "toolName") ?? "").toLowerCase())
+            ? "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)
+        if (applyTo)
             candidateCount++;
         mappings.push({ sourceIndex, message: converted, applyTo, originalText });
     }
@@ -26,8 +35,8 @@ export function buildCompressionPayload(messages, minMessageChars) {
         candidateCount,
     };
 }
-export function applyCompressionResult(originalMessages, mappings, compressedMessages, _options) {
-    if (compressedMessages.length !== mappings.length) {
+export function applyCompressionResult(originalMessages, mappings, compressedMessages, options) {
+    if (!Array.isArray(compressedMessages) || compressedMessages.length !== mappings.length) {
         return { ok: false, reason: "message-count-changed" };
     }
     const nextMessages = structuredClone(originalMessages);
@@ -40,16 +49,21 @@ export function applyCompressionResult(originalMessages, mappings, compressedMes
         // 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)
+        if (!mapping.applyTo || mapping.originalText.length < options.minMessageChars)
             continue;
         const validation = validateAlignedMessage(mapping.message, compressed);
         if (!validation.ok)
             return validation;
-        let nextText = extractOpenAIText(compressed);
+        const nextText = extractOpenAIText(compressed);
         if (nextText === mapping.originalText)
             continue;
-        // Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
-        nextText = naturalizeHeadroomMarkers(nextText);
+        // No retrieval executor is registered. Hiding a hash does not recover evidence.
+        if (CCR_MARKER.test(nextText))
+            return { ok: false, reason: "unrecoverable-ccr-marker" };
+        if (!nextText.trim())
+            return { ok: false, reason: "empty-compressed-content" };
+        if (estimateTokens(nextText) >= estimateTokens(mapping.originalText))
+            continue;
         const target = nextMessages[mapping.sourceIndex];
         if (!hasContent(target) || !replaceTextContent(target, nextText)) {
             return { ok: false, reason: "target-content-unreplaceable" };
@@ -142,14 +156,16 @@ function convertToolCall(toolCall) {
         id: toolCall.id,
         type: "function",
         function: {
-            // Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
-            // Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
-            name: "pi_tool_result",
-            arguments: JSON.stringify({ originalToolName: toolCall.name }),
+            // Preserve upstream tool protections as well as routing context.
+            name: toolCall.name,
+            arguments: JSON.stringify(toolCall.arguments),
         },
     };
 }
 function validateAlignedMessage(original, compressed) {
+    if (!isRecord(compressed) || (original.role === "tool" && typeof compressed.content !== "string")) {
+        return { ok: false, reason: "invalid-compressed-message" };
+    }
     if (original.role !== compressed.role) {
         return { ok: false, reason: `role-changed:${original.role}->${compressed.role}` };
     }
@@ -241,24 +257,3 @@ function estimateTokens(text) {
     // ponytail: cheap local estimate; exact tokenizer would add a heavy dependency for a footer number.
     return text.length === 0 ? 0 : Math.max(1, Math.ceil(text.length / 4));
 }
-function naturalizeHeadroomMarkers(text) {
-    // Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
-    // into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
-    return text.replace(/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi, "[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]");
-}
-export function injectCompressionAwareness(messages) {
-    // If a system message already exists at the top, we append the hint to it.
-    // Otherwise, we inject a new system message at index 0.
-    const result = [...messages];
-    const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
-    const first = result[0];
-    if (first && first.role === "system" && typeof first.content === "string") {
-        if (!first.content.includes("automatically compressed by Headroom")) {
-            result[0] = { ...first, content: `${first.content}\n\n${hintText}` };
-        }
-    }
-    else {
-        result.unshift({ role: "system", content: hintText });
-    }
-    return result;
-}

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { CompressResult, OpenAIMessage } from "./types.js";
+export declare class HeadroomResponseError extends Error {
+}
 interface HeadroomClientOptions {
     baseUrl: string;
     timeoutMs: number;

package/dist/client.js

@@ -1,3 +1,5 @@
+export class HeadroomResponseError extends Error {
+}
 export class HeadroomHttpClient {
     baseUrl;
     timeoutMs;
@@ -8,14 +10,13 @@ export class HeadroomHttpClient {
     async health(signal) {
         try {
             const response = await fetch(`${this.baseUrl}/health`, {
+                redirect: "error",
                 signal: buildSignal(this.timeoutMs, signal),
             });
             if (!response.ok)
                 return false;
             const body = await readJsonObject(response);
-            if (!body)
-                return true;
-            return body.status === "healthy" || body.status === "ok" || "optimize" in body || "stats" in body;
+            return Boolean(body && body.ready !== false && (body.status === "healthy" || body.status === "ok"));
         }
         catch {
             return false;
@@ -24,12 +25,16 @@ export class HeadroomHttpClient {
     async probe(signal) {
         try {
             const response = await fetch(`${this.baseUrl}/v1/compress`, {
+                redirect: "error",
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ messages: [{ role: "user", content: "ping" }], model: "gpt-4o" }),
                 signal: buildSignal(5_000, signal),
             });
-            return response.ok;
+            if (!response.ok)
+                return false;
+            validateCompressionResponse(await response.json());
+            return true;
         }
         catch {
             return false;
@@ -37,6 +42,7 @@ export class HeadroomHttpClient {
     }
     async stats(signal) {
         const response = await fetch(`${this.baseUrl}/stats`, {
+            redirect: "error",
             signal: buildSignal(this.timeoutMs, signal),
         });
         if (!response.ok) {
@@ -46,19 +52,25 @@ export class HeadroomHttpClient {
     }
     async compress(messages, model, signal) {
         const response = await fetch(`${this.baseUrl}/v1/compress`, {
+            redirect: "error",
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
                 "X-Headroom-Stack": "pi-extension",
             },
-            body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+            body: JSON.stringify({
+                messages,
+                model: model || "gpt-4o",
+                // 0.39.1's default is marker-free and inherits the backend's --lossless policy.
+                // lossy_inline would override that policy and enable lossy SmartCrusher.
+            }),
             signal: buildSignal(this.timeoutMs, signal),
         });
         if (!response.ok) {
             const message = await readErrorMessage(response);
             throw new Error(message || `Headroom /v1/compress failed with HTTP ${response.status}`);
         }
-        const payload = (await response.json());
+        const payload = validateCompressionResponse(await response.json());
         return {
             messages: payload.messages,
             tokensBefore: payload.tokens_before,
@@ -71,6 +83,17 @@ export class HeadroomHttpClient {
         };
     }
 }
+function validateCompressionResponse(value) {
+    const metrics = ["tokens_before", "tokens_after", "tokens_saved", "compression_ratio"];
+    const stringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === "string");
+    if (!isRecord(value) || !Array.isArray(value.messages) ||
+        !metrics.every((key) => typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0) ||
+        (value.transforms_applied !== undefined && !stringArray(value.transforms_applied)) ||
+        (value.ccr_hashes != null && !stringArray(value.ccr_hashes))) {
+        throw new HeadroomResponseError("Invalid Headroom compression response");
+    }
+    return value;
+}
 async function readJsonObject(response) {
     try {
         const body = (await response.json());

package/dist/config.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
-const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
+const DEFAULT_MIN_CONTEXT_TOKENS = 10_000;
 const DEFAULT_MIN_MESSAGE_CHARS = 2_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 export const HEADROOM_SETTINGS_DIR = path.join(os.homedir(), ".pi", "agent", "headroom");
@@ -48,7 +48,8 @@ export function loadHeadroomConfig(env = process.env, settings = env === process
 export function isLocalHeadroomUrl(rawUrl) {
     try {
         const url = new URL(rawUrl);
-        return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+        return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password &&
+            ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
     }
     catch {
         return false;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ interface HeadroomRuntimeState {
     lastGuardSkipCandidateFingerprint: string | null;
     seenCandidateContentFingerprints?: Set<string>;
     seenCandidateContentOrder?: string[];
+    compressedCandidates?: Map<string, string>;
     lastCompressionTime: number;
     stats: HeadroomStats;
 }

package/dist/index.js

@@ -1,7 +1,7 @@
 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";
+import { HeadroomHttpClient, HeadroomResponseError } from "./client.js";
 import { isRemoteBlocked, loadHeadroomConfig, saveHeadroomSettings } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
 const STATUS_KEY = "headroom";
@@ -17,6 +17,14 @@ export default function headroomExtension(pi) {
     registerCompressionRenderer(pi);
     const runtime = createRuntime(pi);
     pi.on("session_start", (_event, ctx) => {
+        // A context transform is request-local; cached substitutions must not cross sessions.
+        runtime.state.compressedCandidates = new Map();
+        runtime.state.seenCandidateContentFingerprints = new Set();
+        runtime.state.seenCandidateContentOrder = [];
+        runtime.state.lastInputFingerprint = null;
+        runtime.state.lastOutputFingerprint = null;
+        runtime.state.lastGuardSkipCandidateFingerprint = null;
+        runtime.state.lastCompressionTime = 0;
         if (isRemoteBlocked(runtime.config)) {
             runtime.refreshStatus(ctx);
             emitNotraceTelemetry(runtime);
@@ -79,6 +87,7 @@ function createRuntime(pi) {
         lastGuardSkipCandidateFingerprint: null,
         seenCandidateContentFingerprints: new Set(),
         seenCandidateContentOrder: [],
+        compressedCandidates: new Map(),
         lastCompressionTime: 0,
         stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
     };
@@ -207,33 +216,29 @@ function registerCompressionRenderer(pi) {
 async function handleContextCompression(runtime, event, ctx) {
     if (runtime.state.processing)
         return undefined;
+    let replayed;
     const bypassUncompressed = () => {
         if (runtime.state.stats.last) {
             runtime.state.stats.last = undefined;
             runtime.refreshStatus(ctx);
         }
-        return undefined;
+        return replayed ? { messages: replayed } : undefined;
     };
-    // Throttle: max 1 compression attempt per 3 seconds to kill infinite loops
-    const now = Date.now();
-    if (now - runtime.state.lastCompressionTime < 3000) {
-        return bypassUncompressed();
-    }
-    // Content-based guards to prevent infinite recursion
-    const inputFingerprint = generateFingerprint(event.messages);
-    // 1. If this input matches our previous output, we already compressed it. Stop.
-    if (runtime.state.lastOutputFingerprint === inputFingerprint) {
-        return undefined;
-    }
-    // 2. If this input matches our previous input, it didn't change. Stop.
-    if (runtime.state.lastInputFingerprint === inputFingerprint) {
-        return bypassUncompressed();
-    }
     if (shouldSkipBeforePayload(runtime, ctx))
         return bypassUncompressed();
     const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
+    replayed = replayCachedCandidates(runtime.state, event.messages, payload, runtime.config.minMessageChars);
     if (payload.candidateCount === 0)
         return bypassUncompressed();
+    // Pi's context transform is request-local; reuse validated text on later turns.
+    const now = Date.now();
+    if (now - runtime.state.lastCompressionTime < 3000)
+        return bypassUncompressed();
+    const inputFingerprint = generateFingerprint(event.messages);
+    if (runtime.state.lastOutputFingerprint === inputFingerprint)
+        return undefined;
+    if (runtime.state.lastInputFingerprint === inputFingerprint)
+        return bypassUncompressed();
     // 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);
@@ -276,9 +281,17 @@ 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;
         recordSeenCandidateContent(runtime.state, payload, applied.messages);
+        if (replayed) {
+            for (const mapping of payload.mappings) {
+                if (runtime.state.compressedCandidates?.has(candidateKey(event.messages[mapping.sourceIndex], mapping.originalText))) {
+                    applied.messages[mapping.sourceIndex] = replayed[mapping.sourceIndex];
+                }
+            }
+        }
+        recordCachedCandidates(runtime.state, payload, applied.messages);
+        runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
         const appliedResult = {
             ...result,
             tokensBefore: applied.appliedTokensBefore,
@@ -300,6 +313,43 @@ async function handleContextCompression(runtime, event, ctx) {
         runtime.state.processing = false;
     }
 }
+function candidateKey(message, text) {
+    const source = message;
+    return stableHash(JSON.stringify([source.toolCallId, source.toolName, stableHash(text)]));
+}
+function replayCachedCandidates(state, messages, payload, minMessageChars) {
+    if (!state.compressedCandidates?.size)
+        return undefined;
+    const mappings = payload.mappings.map((mapping) => ({
+        ...mapping,
+        applyTo: mapping.applyTo && state.compressedCandidates?.has(candidateKey(messages[mapping.sourceIndex], mapping.originalText))
+            ? mapping.applyTo : null,
+    }));
+    const compressed = mappings.map((mapping) => {
+        const text = mapping.applyTo && state.compressedCandidates?.get(candidateKey(messages[mapping.sourceIndex], mapping.originalText));
+        return text && mapping.message.role === "tool" ? { ...mapping.message, content: text } : mapping.message;
+    });
+    const applied = applyCompressionResult(messages, mappings, compressed, { minMessageChars });
+    return applied.ok ? applied.messages : undefined;
+}
+function recordCachedCandidates(state, payload, messages) {
+    state.compressedCandidates ??= new Map();
+    for (const mapping of payload.mappings) {
+        if (!mapping.applyTo)
+            continue;
+        const applied = convertMessage(messages[mapping.sourceIndex]);
+        if (!applied || applied.role !== "tool")
+            continue;
+        const text = extractOpenAIText(applied);
+        if (text === mapping.originalText)
+            continue;
+        const key = candidateKey(messages[mapping.sourceIndex], mapping.originalText);
+        state.compressedCandidates.set(key, text);
+        if (state.compressedCandidates.size > MAX_SEEN_CANDIDATE_CONTENT_FINGERPRINTS) {
+            state.compressedCandidates.delete(state.compressedCandidates.keys().next().value);
+        }
+    }
+}
 function allCandidateContentSeen(state, payload) {
     const seen = state.seenCandidateContentFingerprints;
     if (!seen?.size)
@@ -484,7 +534,8 @@ function announceGuardSkip(ctx, reason, result, mode = "normal") {
 }
 function recordCompressionError(runtime, ctx, error) {
     runtime.state.stats.lastError = getErrorMessage(error);
-    if (isAbortOrTimeoutError(error)) {
+    if (isAbortOrTimeoutError(error) || error instanceof HeadroomResponseError) {
+        // The proxy answered; invalid data is not a connectivity failure.
         emitNotraceTelemetry(runtime);
         runtime.refreshStatus(ctx);
         return;

package/dist/proxy-manager.js

@@ -13,27 +13,33 @@ export async function startPersistentHeadroomProxy(config) {
             env: {
                 ...process.env,
                 HEADROOM_TELEMETRY: process.env.HEADROOM_TELEMETRY || "off",
+                HEADROOM_BEACON: process.env.HEADROOM_BEACON || "off",
             },
         });
-        child.unref();
-        return { ok: true };
+        return await new Promise((resolve) => {
+            child.once("error", (error) => resolve({ ok: false, reason: error.message }));
+            child.once("spawn", () => {
+                child.unref();
+                resolve({ ok: true });
+            });
+        });
     }
     catch (error) {
         return { ok: false, reason: error instanceof Error ? error.message : String(error) };
     }
 }
 export function buildProxyArgs(endpoint) {
-    return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "token", "--no-cache"];
+    return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "cache", "--lossless", "--no-cache"];
 }
 export function parseLocalEndpoint(baseUrl) {
     try {
         const url = new URL(baseUrl);
-        if (!["http:", "https:"].includes(url.protocol))
+        if (url.protocol !== "http:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
             return undefined;
         if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname))
             return undefined;
         const host = url.hostname === "localhost" ? "127.0.0.1" : url.hostname.replace(/^\[(.*)]$/, "$1");
-        const port = url.port || "8787";
+        const port = url.port || "80";
         return { host, port };
     }
     catch {

package/extensions/bridge.ts

@@ -17,6 +17,9 @@ interface MessageWithContent {
 }
 
 const STANDARD_COMPRESSIBLE_ROLES = new Set(["user", "assistant", "toolResult"]);
+// File reads supply exact edit anchors; directives and recovered evidence must stay raw.
+const PROTECTED_TOOLS = new Set(["read", "read_file", "view", "edit", "write", "skill", "headroom_retrieve"]);
+const CCR_MARKER = /Retrieve\s+(?:more|original):\s*hash=|<<ccr:/i;
 
 export function buildCompressionPayload(messages: AgentMessage[], minMessageChars: number): CompressionPayload {
 	const mappings: CompressionMapping[] = [];
@@ -30,7 +33,13 @@ export function buildCompressionPayload(messages: AgentMessage[], minMessageChar
 		const originalText = extractOpenAIText(converted);
 		// Mark candidates for compression.
 		// ONLY toolResults are candidates, preserving original Pi conversation fidelity.
-		let applyTo: "toolResult" | null = source.role === "toolResult" ? "toolResult" : null;
+		const textOnly = typeof source.content === "string" ||
+			(Array.isArray(source.content) && source.content.every(isTextContent));
+		let applyTo: "toolResult" | null = source.role === "toolResult" &&
+			textOnly && originalText.length >= minMessageChars &&
+			!("isError" in source && source.isError) &&
+			!PROTECTED_TOOLS.has((readStringProperty(source, "toolName") ?? "").toLowerCase())
+			? "toolResult" : null;
 
 		// Headroom Bypass Rules (Android Hat)
 		// We never want to compress `android layout` JSON dumps or critical adb dumps.
@@ -38,7 +47,7 @@ export function buildCompressionPayload(messages: AgentMessage[], minMessageChar
 			applyTo = null;
 		}
 		
-		if (applyTo && originalText.length >= minMessageChars) candidateCount++;
+		if (applyTo) candidateCount++;
 		mappings.push({ sourceIndex, message: converted, applyTo, originalText });
 	}
 
@@ -53,9 +62,9 @@ export function applyCompressionResult(
 	originalMessages: AgentMessage[],
 	mappings: CompressionMapping[],
 	compressedMessages: OpenAIMessage[],
-	_options: ApplyCompressionOptions,
+	options: ApplyCompressionOptions,
 ): ApplyCompressionResult {
-	if (compressedMessages.length !== mappings.length) {
+	if (!Array.isArray(compressedMessages) || compressedMessages.length !== mappings.length) {
 		return { ok: false, reason: "message-count-changed" };
 	}
 
@@ -71,16 +80,17 @@ export function applyCompressionResult(
 		// 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;
+		if (!mapping.applyTo || mapping.originalText.length < options.minMessageChars) continue;
 
 		const validation = validateAlignedMessage(mapping.message, compressed);
 		if (!validation.ok) return validation;
 
-		let nextText = extractOpenAIText(compressed);
+		const nextText = extractOpenAIText(compressed);
 		if (nextText === mapping.originalText) continue;
-
-		// Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
-		nextText = naturalizeHeadroomMarkers(nextText);
+		// No retrieval executor is registered. Hiding a hash does not recover evidence.
+		if (CCR_MARKER.test(nextText)) return { ok: false, reason: "unrecoverable-ccr-marker" };
+		if (!nextText.trim()) return { ok: false, reason: "empty-compressed-content" };
+		if (estimateTokens(nextText) >= estimateTokens(mapping.originalText)) continue;
 
 		const target = nextMessages[mapping.sourceIndex] as AnyMessage;
 		if (!hasContent(target) || !replaceTextContent(target, nextText)) {
@@ -175,10 +185,9 @@ function convertToolCall(toolCall: ToolCall): OpenAIToolCall {
 		id: toolCall.id,
 		type: "function",
 		function: {
-			// Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
-			// Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
-			name: "pi_tool_result",
-			arguments: JSON.stringify({ originalToolName: toolCall.name }),
+			// Preserve upstream tool protections as well as routing context.
+			name: toolCall.name,
+			arguments: JSON.stringify(toolCall.arguments),
 		},
 	};
 }
@@ -187,6 +196,9 @@ function validateAlignedMessage(
 	original: OpenAIMessage,
 	compressed: OpenAIMessage,
 ): { ok: true } | { ok: false; reason: string } {
+	if (!isRecord(compressed) || (original.role === "tool" && typeof compressed.content !== "string")) {
+		return { ok: false, reason: "invalid-compressed-message" };
+	}
 	if (original.role !== compressed.role) {
 		return { ok: false, reason: `role-changed:${original.role}->${compressed.role}` };
 	}
@@ -287,30 +299,3 @@ function estimateTokens(text: string): number {
 	// ponytail: cheap local estimate; exact tokenizer would add a heavy dependency for a footer number.
 	return text.length === 0 ? 0 : Math.max(1, Math.ceil(text.length / 4));
 }
-
-function naturalizeHeadroomMarkers(text: string): string {
-	// Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
-	// into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
-	return text.replace(
-		/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi,
-		"[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]"
-	);
-}
-
-export function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[] {
-	// If a system message already exists at the top, we append the hint to it.
-	// Otherwise, we inject a new system message at index 0.
-	const result = [...messages];
-	const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
-
-	const first = result[0] as unknown as Record<string, unknown>;
-	if (first && first.role === "system" && typeof first.content === "string") {
-		if (!first.content.includes("automatically compressed by Headroom")) {
-			result[0] = { ...first, content: `${first.content}\n\n${hintText}` } as unknown as AgentMessage;
-		}
-	} else {
-		result.unshift({ role: "system", content: hintText } as unknown as AgentMessage);
-	}
-
-	return result;
-}

package/extensions/client.ts

@@ -10,6 +10,8 @@ interface ProxyCompressResponse {
 	ccr_hashes?: string[];
 }
 
+export class HeadroomResponseError extends Error {}
+
 interface HeadroomClientOptions {
 	baseUrl: string;
 	timeoutMs: number;
@@ -27,12 +29,12 @@ export class HeadroomHttpClient {
 	async health(signal?: AbortSignal): Promise<boolean> {
 		try {
 			const response = await fetch(`${this.baseUrl}/health`, {
+				redirect: "error",
 				signal: buildSignal(this.timeoutMs, signal),
 			});
 			if (!response.ok) return false;
 			const body = await readJsonObject(response);
-			if (!body) return true;
-			return body.status === "healthy" || body.status === "ok" || "optimize" in body || "stats" in body;
+			return Boolean(body && body.ready !== false && (body.status === "healthy" || body.status === "ok"));
 		} catch {
 			return false;
 		}
@@ -41,12 +43,15 @@ export class HeadroomHttpClient {
 	async probe(signal?: AbortSignal): Promise<boolean> {
 		try {
 			const response = await fetch(`${this.baseUrl}/v1/compress`, {
+				redirect: "error",
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
 				body: JSON.stringify({ messages: [{ role: "user", content: "ping" }], model: "gpt-4o" }),
 				signal: buildSignal(5_000, signal),
 			});
-			return response.ok;
+			if (!response.ok) return false;
+			validateCompressionResponse(await response.json());
+			return true;
 		} catch {
 			return false;
 		}
@@ -54,6 +59,7 @@ export class HeadroomHttpClient {
 
 	async stats(signal?: AbortSignal): Promise<unknown> {
 		const response = await fetch(`${this.baseUrl}/stats`, {
+			redirect: "error",
 			signal: buildSignal(this.timeoutMs, signal),
 		});
 		if (!response.ok) {
@@ -64,12 +70,18 @@ export class HeadroomHttpClient {
 
 	async compress(messages: OpenAIMessage[], model: string | undefined, signal?: AbortSignal): Promise<CompressResult> {
 		const response = await fetch(`${this.baseUrl}/v1/compress`, {
+			redirect: "error",
 			method: "POST",
 			headers: {
 				"Content-Type": "application/json",
 				"X-Headroom-Stack": "pi-extension",
 			},
-			body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+			body: JSON.stringify({
+				messages,
+				model: model || "gpt-4o",
+				// 0.39.1's default is marker-free and inherits the backend's --lossless policy.
+				// lossy_inline would override that policy and enable lossy SmartCrusher.
+			}),
 			signal: buildSignal(this.timeoutMs, signal),
 		});
 
@@ -78,7 +90,7 @@ export class HeadroomHttpClient {
 			throw new Error(message || `Headroom /v1/compress failed with HTTP ${response.status}`);
 		}
 
-		const payload = (await response.json()) as ProxyCompressResponse;
+		const payload = validateCompressionResponse(await response.json());
 		return {
 			messages: payload.messages,
 			tokensBefore: payload.tokens_before,
@@ -92,6 +104,18 @@ export class HeadroomHttpClient {
 	}
 }
 
+function validateCompressionResponse(value: unknown): ProxyCompressResponse {
+	const metrics = ["tokens_before", "tokens_after", "tokens_saved", "compression_ratio"];
+	const stringArray = (v: unknown) => Array.isArray(v) && v.every((item) => typeof item === "string");
+	if (!isRecord(value) || !Array.isArray(value.messages) ||
+		!metrics.every((key) => typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0) ||
+		(value.transforms_applied !== undefined && !stringArray(value.transforms_applied)) ||
+		(value.ccr_hashes != null && !stringArray(value.ccr_hashes))) {
+		throw new HeadroomResponseError("Invalid Headroom compression response");
+	}
+	return value as unknown as ProxyCompressResponse;
+}
+
 async function readJsonObject(response: Response): Promise<Record<string, unknown> | undefined> {
 	try {
 		const body = (await response.json()) as unknown;

package/extensions/config.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import type { HeadroomConfig, HeadroomMode } from "./types.js";
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
-const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
+const DEFAULT_MIN_CONTEXT_TOKENS = 10_000;
 const DEFAULT_MIN_MESSAGE_CHARS = 2_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -84,7 +84,8 @@ export function loadHeadroomConfig(
 export function isLocalHeadroomUrl(rawUrl: string): boolean {
 	try {
 		const url = new URL(rawUrl);
-		return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+		return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password &&
+			["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
 	} catch {
 		return false;
 	}

package/extensions/index.ts

@@ -7,7 +7,7 @@ import {
 	convertMessage,
 	extractOpenAIText,
 } from "./bridge.js";
-import { HeadroomHttpClient } from "./client.js";
+import { HeadroomHttpClient, HeadroomResponseError } from "./client.js";
 import { isRemoteBlocked, loadHeadroomConfig, saveHeadroomSettings } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
 import type { AgentMessage, CompressResult, CompressionPayload, HeadroomConfig, HeadroomMode, HeadroomStats } from "./types.js";
@@ -36,6 +36,7 @@ interface HeadroomRuntimeState {
 	lastGuardSkipCandidateFingerprint: string | null;
 	seenCandidateContentFingerprints?: Set<string>;
 	seenCandidateContentOrder?: string[];
+	compressedCandidates?: Map<string, string>;
 	lastCompressionTime: number;
 	stats: HeadroomStats;
 }
@@ -67,6 +68,14 @@ export default function headroomExtension(pi: ExtensionAPI) {
 	const runtime = createRuntime(pi);
 
 	pi.on("session_start", (_event, ctx) => {
+		// A context transform is request-local; cached substitutions must not cross sessions.
+		runtime.state.compressedCandidates = new Map();
+		runtime.state.seenCandidateContentFingerprints = new Set();
+		runtime.state.seenCandidateContentOrder = [];
+		runtime.state.lastInputFingerprint = null;
+		runtime.state.lastOutputFingerprint = null;
+		runtime.state.lastGuardSkipCandidateFingerprint = null;
+		runtime.state.lastCompressionTime = 0;
 		if (isRemoteBlocked(runtime.config)) {
 			runtime.refreshStatus(ctx);
 			emitNotraceTelemetry(runtime);
@@ -135,6 +144,7 @@ function createRuntime(pi: ExtensionAPI): HeadroomRuntime {
 		lastGuardSkipCandidateFingerprint: null,
 		seenCandidateContentFingerprints: new Set(),
 		seenCandidateContentOrder: [],
+		compressedCandidates: new Map(),
 		lastCompressionTime: 0,
 		stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
 	};
@@ -270,37 +280,27 @@ async function handleContextCompression(
 ): Promise<{ messages?: AgentMessage[] } | undefined> {
 	if (runtime.state.processing) return undefined;
 
+	let replayed: AgentMessage[] | undefined;
 	const bypassUncompressed = () => {
 		if (runtime.state.stats.last) {
 			runtime.state.stats.last = undefined;
 			runtime.refreshStatus(ctx);
 		}
-		return undefined;
+		return replayed ? { messages: replayed } : undefined;
 	};
 
-	// Throttle: max 1 compression attempt per 3 seconds to kill infinite loops
-	const now = Date.now();
-	if (now - runtime.state.lastCompressionTime < 3000) {
-		return bypassUncompressed();
-	}
-
-	// Content-based guards to prevent infinite recursion
-	const inputFingerprint = generateFingerprint(event.messages);
-
-	// 1. If this input matches our previous output, we already compressed it. Stop.
-	if (runtime.state.lastOutputFingerprint === inputFingerprint) {
-		return undefined;
-	}
-
-	// 2. If this input matches our previous input, it didn't change. Stop.
-	if (runtime.state.lastInputFingerprint === inputFingerprint) {
-		return bypassUncompressed();
-	}
-
 	if (shouldSkipBeforePayload(runtime, ctx)) return bypassUncompressed();
 	const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
+	replayed = replayCachedCandidates(runtime.state, event.messages, payload, runtime.config.minMessageChars);
 	if (payload.candidateCount === 0) return bypassUncompressed();
 
+	// Pi's context transform is request-local; reuse validated text on later turns.
+	const now = Date.now();
+	if (now - runtime.state.lastCompressionTime < 3000) return bypassUncompressed();
+	const inputFingerprint = generateFingerprint(event.messages);
+	if (runtime.state.lastOutputFingerprint === inputFingerprint) return undefined;
+	if (runtime.state.lastInputFingerprint === inputFingerprint) return bypassUncompressed();
+
 	// 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);
@@ -347,9 +347,17 @@ async function handleContextCompression(
 
 		// Store fingerprints to break the feedback loop
 		runtime.state.lastInputFingerprint = inputFingerprint;
-		runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
 		runtime.state.lastGuardSkipCandidateFingerprint = null;
 		recordSeenCandidateContent(runtime.state, payload, applied.messages);
+		if (replayed) {
+			for (const mapping of payload.mappings) {
+				if (runtime.state.compressedCandidates?.has(candidateKey(event.messages[mapping.sourceIndex], mapping.originalText))) {
+					applied.messages[mapping.sourceIndex] = replayed[mapping.sourceIndex];
+				}
+			}
+		}
+		recordCachedCandidates(runtime.state, payload, applied.messages);
+		runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
 		const appliedResult = {
 			...result,
 			tokensBefore: applied.appliedTokensBefore,
@@ -371,6 +379,44 @@ async function handleContextCompression(
 	}
 }
 
+function candidateKey(message: AgentMessage, text: string): string {
+	const source = message as AgentMessage & { toolCallId?: string; toolName?: string };
+	return stableHash(JSON.stringify([source.toolCallId, source.toolName, stableHash(text)]));
+}
+
+function replayCachedCandidates(
+	state: HeadroomRuntimeState, messages: AgentMessage[], payload: CompressionPayload, minMessageChars: number,
+): AgentMessage[] | undefined {
+	if (!state.compressedCandidates?.size) return undefined;
+	const mappings = payload.mappings.map((mapping) => ({
+		...mapping,
+		applyTo: mapping.applyTo && state.compressedCandidates?.has(candidateKey(messages[mapping.sourceIndex], mapping.originalText))
+			? mapping.applyTo : null,
+	}));
+	const compressed = mappings.map((mapping) => {
+		const text = mapping.applyTo && state.compressedCandidates?.get(candidateKey(messages[mapping.sourceIndex], mapping.originalText));
+		return text && mapping.message.role === "tool" ? { ...mapping.message, content: text } : mapping.message;
+	});
+	const applied = applyCompressionResult(messages, mappings, compressed, { minMessageChars });
+	return applied.ok ? applied.messages : undefined;
+}
+
+function recordCachedCandidates(state: HeadroomRuntimeState, payload: CompressionPayload, messages: AgentMessage[]): void {
+	state.compressedCandidates ??= new Map();
+	for (const mapping of payload.mappings) {
+		if (!mapping.applyTo) continue;
+		const applied = convertMessage(messages[mapping.sourceIndex]);
+		if (!applied || applied.role !== "tool") continue;
+		const text = extractOpenAIText(applied);
+		if (text === mapping.originalText) continue;
+		const key = candidateKey(messages[mapping.sourceIndex], mapping.originalText);
+		state.compressedCandidates.set(key, text);
+		if (state.compressedCandidates.size > MAX_SEEN_CANDIDATE_CONTENT_FINGERPRINTS) {
+			state.compressedCandidates.delete(state.compressedCandidates.keys().next().value!);
+		}
+	}
+}
+
 function allCandidateContentSeen(state: HeadroomRuntimeState, payload: CompressionPayload): boolean {
 	const seen = state.seenCandidateContentFingerprints;
 	if (!seen?.size) return false;
@@ -564,7 +610,8 @@ 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)) {
+	if (isAbortOrTimeoutError(error) || error instanceof HeadroomResponseError) {
+		// The proxy answered; invalid data is not a connectivity failure.
 		emitNotraceTelemetry(runtime);
 		runtime.refreshStatus(ctx);
 		return;

package/extensions/proxy-manager.ts

@@ -22,26 +22,32 @@ export async function startPersistentHeadroomProxy(
 			env: {
 				...process.env,
 				HEADROOM_TELEMETRY: process.env.HEADROOM_TELEMETRY || "off",
+				HEADROOM_BEACON: process.env.HEADROOM_BEACON || "off",
 			},
 		});
-		child.unref();
-		return { ok: true };
+		return await new Promise((resolve) => {
+			child.once("error", (error) => resolve({ ok: false, reason: error.message }));
+			child.once("spawn", () => {
+				child.unref();
+				resolve({ ok: true });
+			});
+		});
 	} catch (error) {
 		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
 	}
 }
 
 export function buildProxyArgs(endpoint: ProxyEndpoint): string[] {
-	return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "token", "--no-cache"];
+	return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "cache", "--lossless", "--no-cache"];
 }
 
 export function parseLocalEndpoint(baseUrl: string): ProxyEndpoint | undefined {
 	try {
 		const url = new URL(baseUrl);
-		if (!["http:", "https:"].includes(url.protocol)) return undefined;
+		if (url.protocol !== "http:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) return undefined;
 		if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname)) return undefined;
 		const host = url.hostname === "localhost" ? "127.0.0.1" : url.hostname.replace(/^\[(.*)]$/, "$1");
-		const port = url.port || "8787";
+		const port = url.port || "80";
 		return { host, port };
 	} catch {
 		return undefined;

package/package.json

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