@ryan_nookpi/pi-extension-headroom 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @ryan_nookpi/pi-extension-headroom
+
+This extension reclaims context window in pi by compressing large tool results through a [Headroom](https://github.com/headroom-ai/headroom) proxy before each LLM call.
+
+Headroom runs locally, compresses only oversized `toolResult` payloads, and leaves your prompts, assistant turns, and tool-call metadata untouched. Compression is applied only when the proxy is online and the change passes strict alignment guards, so it never silently rewrites your conversation.
+
+## Install
+
+```bash
+pi install npm:@ryan_nookpi/pi-extension-headroom
+```
+
+You also need the Headroom proxy available on your machine:
+
+```bash
+pip install "headroom-ai[proxy]"
+```
+
+By default the extension auto-starts a local token-mode proxy (`headroom proxy --mode token --no-cache`) on `http://127.0.0.1:8788` and leaves it running after pi exits.
+
+## How it works
+
+- Listens on the `context` event fired before each LLM call.
+- Skips entirely until context usage reaches the configured token threshold.
+- Sends an OpenAI-shaped copy of the conversation to the proxy's `/v1/compress` endpoint.
+- Applies the result only to large `toolResult` messages, preserving pi metadata (`toolName`, `details`, tool-call ids, images).
+- Rejects any response that changes message count, roles, tool-call ids, or non-candidate content.
+
+## Privacy
+
+Compression sends conversation context to the proxy, so remote URLs are blocked by default. Only `localhost`/`127.0.0.1`/`::1` are allowed unless you explicitly set `PI_HEADROOM_ALLOW_REMOTE=1` for a proxy you trust.
+
+## Commands
+
+- `/headroom` — show current status and session stats.
+- `/headroom on` — enable compression and ensure the proxy is running.
+- `/headroom off` — disable compression for this session (the proxy keeps running).
+- `/headroom health` — check / start the proxy and report whether it is online.
+- `/headroom stats` — print the proxy's own `/stats` output.
+- `/headroom-health` — shortcut for `/headroom health`.
+
+The footer shows a compact status (`✓ Headroom -42% (12,345 saved)`) once compression is applied.
+
+## Configuration
+
+All settings are environment variables read at startup:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PI_HEADROOM_ENABLED` | `true` | Enable compression on start. |
+| `PI_HEADROOM_URL` | `http://127.0.0.1:8788` | Proxy base URL (`HEADROOM_URL` / `HEADROOM_BASE_URL` also accepted). |
+| `PI_HEADROOM_ALLOW_REMOTE` | `false` | Allow non-local proxy URLs. |
+| `PI_HEADROOM_AUTO_START` | `true` | Auto-start a local persistent proxy when offline. |
+| `PI_HEADROOM_COMMAND` | `headroom` | Command used to launch the proxy. |
+| `PI_HEADROOM_MIN_CONTEXT_TOKENS` | `20000` | Skip compression below this context token count. |
+| `PI_HEADROOM_MIN_MESSAGE_CHARS` | `2000` | Only compress tool results at or above this size. |
+| `PI_HEADROOM_TIMEOUT_MS` | `15000` | HTTP timeout for proxy requests. |
+
+Boolean values accept `1/0`, `true/false`, `yes/no`, `on/off`.

package/bridge.ts

@@ -0,0 +1,238 @@
+import type { ImageContent, TextContent, ToolCall } from "@earendil-works/pi-ai";
+import type {
+	AgentMessage,
+	ApplyCompressionOptions,
+	ApplyCompressionResult,
+	CompressionMapping,
+	CompressionPayload,
+	OpenAIAssistantMessage,
+	OpenAIMessage,
+	OpenAIToolCall,
+} from "./types.ts";
+
+type AnyMessage = AgentMessage & { role?: string; content?: unknown; timestamp?: number };
+
+interface MessageWithContent {
+	content: unknown;
+}
+
+const STANDARD_COMPRESSIBLE_ROLES = new Set(["user", "assistant", "toolResult"]);
+
+export function buildCompressionPayload(messages: AgentMessage[], minMessageChars: number): CompressionPayload {
+	const mappings: CompressionMapping[] = [];
+	let candidateCount = 0;
+
+	for (let sourceIndex = 0; sourceIndex < messages.length; sourceIndex++) {
+		const source = messages[sourceIndex] as AnyMessage;
+		const converted = convertMessage(source);
+		if (!converted) continue;
+
+		const originalText = extractOpenAIText(converted);
+		const applyTo = source.role === "toolResult" && originalText.length >= minMessageChars ? "toolResult" : null;
+		if (applyTo) candidateCount++;
+		mappings.push({ sourceIndex, message: converted, applyTo, originalText });
+	}
+
+	return {
+		messages: mappings.map((mapping) => mapping.message),
+		mappings,
+		candidateCount,
+	};
+}
+
+export function applyCompressionResult(
+	originalMessages: AgentMessage[],
+	mappings: CompressionMapping[],
+	compressedMessages: OpenAIMessage[],
+	_options: ApplyCompressionOptions,
+): ApplyCompressionResult {
+	if (compressedMessages.length !== mappings.length) {
+		return { ok: false, reason: "message-count-changed" };
+	}
+
+	const nextMessages = structuredClone(originalMessages) as AgentMessage[];
+	let appliedMessages = 0;
+
+	for (let index = 0; index < mappings.length; index++) {
+		const mapping = mappings[index];
+		const compressed = compressedMessages[index];
+		const validation = validateAlignedMessage(mapping.message, compressed);
+		if (!validation.ok) return validation;
+
+		const 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)) {
+			return { ok: false, reason: "target-content-unreplaceable" };
+		}
+		appliedMessages++;
+	}
+
+	if (appliedMessages === 0) {
+		return { ok: false, reason: "no-applicable-message-changed" };
+	}
+
+	return { ok: true, messages: nextMessages, appliedMessages };
+}
+
+function convertMessage(message: AnyMessage): OpenAIMessage | undefined {
+	if (!message.role || !STANDARD_COMPRESSIBLE_ROLES.has(message.role)) return undefined;
+	switch (message.role) {
+		case "user":
+			return convertUserMessage(message);
+		case "assistant":
+			return convertAssistantMessage(message);
+		case "toolResult":
+			return convertToolResultMessage(message);
+		default:
+			return undefined;
+	}
+}
+
+function convertUserMessage(message: AnyMessage): OpenAIMessage | undefined {
+	if (!hasContent(message)) return undefined;
+	if (typeof message.content === "string") {
+		return { role: "user", content: message.content };
+	}
+	if (!Array.isArray(message.content)) return undefined;
+
+	const text = message.content
+		.filter((part): part is TextContent => isTextContent(part))
+		.map((part) => part.text)
+		.join("\n");
+	if (text) return { role: "user", content: text };
+	const hasImages = message.content.some((part) => isImageContent(part));
+	return hasImages ? { role: "user", content: "[image omitted from Headroom compression payload]" } : undefined;
+}
+
+function convertAssistantMessage(message: AnyMessage): OpenAIAssistantMessage | undefined {
+	if (!hasContent(message) || !Array.isArray(message.content)) return undefined;
+	const text = message.content
+		.filter((part): part is TextContent => isTextContent(part))
+		.map((part) => part.text)
+		.join("");
+	const toolCalls = message.content.filter((part): part is ToolCall => isToolCall(part));
+	if (!text && toolCalls.length === 0) return undefined;
+
+	const converted: OpenAIAssistantMessage = {
+		role: "assistant",
+		content: text || null,
+	};
+	if (toolCalls.length > 0) {
+		converted.tool_calls = toolCalls.map(convertToolCall);
+	}
+	return converted;
+}
+
+function convertToolResultMessage(message: AnyMessage): OpenAIMessage | undefined {
+	if (!hasContent(message)) return undefined;
+	const toolCallId = readStringProperty(message, "toolCallId");
+	if (!toolCallId) return undefined;
+	return {
+		role: "tool",
+		content: extractTextFromContent(message.content),
+		tool_call_id: toolCallId,
+	};
+}
+
+function convertToolCall(toolCall: ToolCall): OpenAIToolCall {
+	return {
+		id: toolCall.id,
+		type: "function",
+		function: {
+			name: toolCall.name,
+			arguments: JSON.stringify(toolCall.arguments),
+		},
+	};
+}
+
+function validateAlignedMessage(
+	original: OpenAIMessage,
+	compressed: OpenAIMessage,
+): { ok: true } | { ok: false; reason: string } {
+	if (original.role !== compressed.role) {
+		return { ok: false, reason: `role-changed:${original.role}->${compressed.role}` };
+	}
+	if (original.role === "tool" && compressed.role === "tool") {
+		if (original.tool_call_id !== compressed.tool_call_id) return { ok: false, reason: "tool-call-id-changed" };
+	}
+	if (original.role === "assistant" && compressed.role === "assistant") {
+		const originalIds = (original.tool_calls ?? []).map((call) => call.id).join("\n");
+		const compressedIds = (compressed.tool_calls ?? []).map((call) => call.id).join("\n");
+		if (originalIds !== compressedIds) return { ok: false, reason: "assistant-tool-calls-changed" };
+	}
+	return { ok: true };
+}
+
+function extractOpenAIText(message: OpenAIMessage): string {
+	if (message.role === "assistant") return typeof message.content === "string" ? message.content : "";
+	if (message.role === "tool" || message.role === "system") return message.content;
+	if (typeof message.content === "string") return message.content;
+	return message.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function extractTextFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((part): part is TextContent => isTextContent(part))
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function replaceTextContent(message: MessageWithContent, text: string): boolean {
+	if (typeof message.content === "string") {
+		message.content = text;
+		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];
+	return true;
+}
+
+function hasContent(message: AnyMessage): message is AnyMessage & MessageWithContent {
+	return "content" in message;
+}
+
+function isTextContent(value: unknown): value is TextContent {
+	return isRecord(value) && value.type === "text" && typeof value.text === "string";
+}
+
+function isImageContent(value: unknown): value is ImageContent {
+	return (
+		isRecord(value) && value.type === "image" && typeof value.data === "string" && typeof value.mimeType === "string"
+	);
+}
+
+function isToolCall(value: unknown): value is ToolCall {
+	return (
+		isRecord(value) &&
+		value.type === "toolCall" &&
+		typeof value.id === "string" &&
+		typeof value.name === "string" &&
+		isRecord(value.arguments)
+	);
+}
+
+function readStringProperty(value: unknown, key: string): string | undefined {
+	if (!isRecord(value)) return undefined;
+	const property = value[key];
+	return typeof property === "string" ? property : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/client.ts

@@ -0,0 +1,112 @@
+import type { CompressResult, OpenAIMessage } from "./types.ts";
+
+interface ProxyCompressResponse {
+	messages: OpenAIMessage[];
+	tokens_before: number;
+	tokens_after: number;
+	tokens_saved: number;
+	compression_ratio: number;
+	transforms_applied: string[];
+	ccr_hashes?: string[];
+}
+
+interface HeadroomClientOptions {
+	baseUrl: string;
+	timeoutMs: number;
+}
+
+export class HeadroomHttpClient {
+	private readonly baseUrl: string;
+	private readonly timeoutMs: number;
+
+	constructor(options: HeadroomClientOptions) {
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.timeoutMs = options.timeoutMs;
+	}
+
+	async health(signal?: AbortSignal): Promise<boolean> {
+		try {
+			const response = await fetch(`${this.baseUrl}/health`, {
+				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;
+		} catch {
+			return false;
+		}
+	}
+
+	async stats(signal?: AbortSignal): Promise<unknown> {
+		const response = await fetch(`${this.baseUrl}/stats`, {
+			signal: buildSignal(this.timeoutMs, signal),
+		});
+		if (!response.ok) {
+			throw new Error(`Headroom /stats failed with HTTP ${response.status}`);
+		}
+		return response.json();
+	}
+
+	async compress(messages: OpenAIMessage[], model: string | undefined, signal?: AbortSignal): Promise<CompressResult> {
+		const response = await fetch(`${this.baseUrl}/v1/compress`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-Headroom-Stack": "pi-extension",
+			},
+			body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+			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()) as ProxyCompressResponse;
+		return {
+			messages: payload.messages,
+			tokensBefore: payload.tokens_before,
+			tokensAfter: payload.tokens_after,
+			tokensSaved: payload.tokens_saved,
+			compressionRatio: payload.compression_ratio,
+			transformsApplied: payload.transforms_applied ?? [],
+			ccrHashes: payload.ccr_hashes ?? [],
+			compressed: true,
+		};
+	}
+}
+
+async function readJsonObject(response: Response): Promise<Record<string, unknown> | undefined> {
+	try {
+		const body = (await response.json()) as unknown;
+		return isRecord(body) ? body : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function readErrorMessage(response: Response): Promise<string | undefined> {
+	try {
+		const body = (await response.json()) as unknown;
+		if (!isRecord(body)) return undefined;
+		const error = body.error;
+		if (isRecord(error) && typeof error.message === "string") return error.message;
+		if (typeof body.message === "string") return body.message;
+	} catch {
+		// Ignore malformed error bodies.
+	}
+	return undefined;
+}
+
+function buildSignal(timeoutMs: number, signal?: AbortSignal): AbortSignal {
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	if (!signal) return timeoutSignal;
+	if (signal.aborted) return signal;
+	return AbortSignal.any([signal, timeoutSignal]);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/config.ts

@@ -0,0 +1,55 @@
+import type { HeadroomConfig } from "./types.ts";
+
+const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
+const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
+const DEFAULT_MIN_MESSAGE_CHARS = 2_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export function loadHeadroomConfig(env: NodeJS.ProcessEnv = process.env): HeadroomConfig {
+	const baseUrl = normalizeBaseUrl(
+		env.PI_HEADROOM_URL || env.HEADROOM_URL || env.HEADROOM_BASE_URL || DEFAULT_BASE_URL,
+	);
+	return {
+		enabled: parseBoolean(env.PI_HEADROOM_ENABLED, true),
+		baseUrl,
+		allowRemote: parseBoolean(env.PI_HEADROOM_ALLOW_REMOTE, false),
+		autoStart: parseBoolean(env.PI_HEADROOM_AUTO_START, true),
+		command: env.PI_HEADROOM_COMMAND?.trim() || "headroom",
+		minContextTokens: parseInteger(env.PI_HEADROOM_MIN_CONTEXT_TOKENS, DEFAULT_MIN_CONTEXT_TOKENS, 0),
+		minMessageChars: parseInteger(env.PI_HEADROOM_MIN_MESSAGE_CHARS, DEFAULT_MIN_MESSAGE_CHARS, 1),
+		timeoutMs: parseInteger(env.PI_HEADROOM_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100),
+	};
+}
+
+export function isLocalHeadroomUrl(rawUrl: string): boolean {
+	try {
+		const url = new URL(rawUrl);
+		return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+	} catch {
+		return false;
+	}
+}
+
+export function isRemoteBlocked(config: Pick<HeadroomConfig, "baseUrl" | "allowRemote">): boolean {
+	return !config.allowRemote && !isLocalHeadroomUrl(config.baseUrl);
+}
+
+function normalizeBaseUrl(raw: string): string {
+	const trimmed = raw.trim() || DEFAULT_BASE_URL;
+	return trimmed.replace(/\/+$/, "");
+}
+
+function parseBoolean(raw: string | undefined, fallback: boolean): boolean {
+	if (raw === undefined) return fallback;
+	const normalized = raw.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return fallback;
+}
+
+function parseInteger(raw: string | undefined, fallback: number, min: number): number {
+	if (raw === undefined) return fallback;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < min) return fallback;
+	return parsed;
+}

package/index.ts

@@ -0,0 +1,416 @@
+import type { ContextEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applyCompressionResult, buildCompressionPayload } from "./bridge.ts";
+import { HeadroomHttpClient } from "./client.ts";
+import { isRemoteBlocked, loadHeadroomConfig } from "./config.ts";
+import { startPersistentHeadroomProxy } from "./proxy-manager.ts";
+import type { AgentMessage, CompressResult, HeadroomConfig, HeadroomStats } from "./types.ts";
+
+const STATUS_KEY = "headroom";
+const SUBCOMMANDS = ["status", "on", "off", "health", "stats"] as const;
+
+type Subcommand = (typeof SUBCOMMANDS)[number];
+
+interface HeadroomRuntimeState {
+	enabled: boolean;
+	proxyOnline: boolean | null;
+	proxyStarting: boolean;
+	proxyStartAttempted: boolean;
+	remoteWarningShown: boolean;
+	offlineWarningShown: boolean;
+	stats: HeadroomStats;
+}
+
+interface HeadroomRuntime {
+	config: HeadroomConfig;
+	client: HeadroomHttpClient;
+	state: HeadroomRuntimeState;
+	refreshStatus(ctx: ExtensionContext): void;
+	updateHealth(ctx: ExtensionContext): Promise<boolean>;
+	ensureProxy(ctx: ExtensionContext): Promise<boolean>;
+}
+
+export default function headroomExtension(pi: ExtensionAPI) {
+	const runtime = createRuntime();
+
+	pi.on("session_start", (_event, ctx) => {
+		if (isRemoteBlocked(runtime.config)) {
+			runtime.refreshStatus(ctx);
+			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);
+		if (!runtime.state.enabled) return;
+		void ensureProxyInBackground(runtime, ctx);
+	});
+
+	pi.on("context", (event, ctx) => handleContextCompression(runtime, event, ctx));
+
+	pi.registerCommand("headroom", {
+		description: "Headroom token compression. Usage: /headroom [on|off|status|health|stats]",
+		getArgumentCompletions(argumentPrefix) {
+			const prefix = argumentPrefix.trim().toLowerCase();
+			return SUBCOMMANDS.filter((command) => command.startsWith(prefix)).map((command) => ({
+				value: command,
+				label: command,
+			}));
+		},
+		handler: async (args, ctx) => handleCommand(runtime, parseSubcommand(args), ctx),
+	});
+
+	pi.registerCommand("headroom-health", {
+		description: "Check Headroom proxy health",
+		handler: async (_args, ctx) => {
+			await handleCommand(runtime, "health", ctx);
+		},
+	});
+}
+
+function createRuntime(): HeadroomRuntime {
+	const config = loadHeadroomConfig();
+	const client = new HeadroomHttpClient({ baseUrl: config.baseUrl, timeoutMs: config.timeoutMs });
+	const state: HeadroomRuntimeState = {
+		enabled: config.enabled,
+		proxyOnline: null,
+		proxyStarting: false,
+		proxyStartAttempted: false,
+		remoteWarningShown: false,
+		offlineWarningShown: false,
+		stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
+	};
+
+	const runtime: HeadroomRuntime = {
+		config,
+		client,
+		state,
+		refreshStatus(ctx) {
+			refreshStatus(ctx, runtime.config, runtime.state);
+		},
+		async updateHealth(ctx) {
+			const online = await updateHealthState(runtime, ctx.signal);
+			runtime.refreshStatus(ctx);
+			return online;
+		},
+		async ensureProxy(ctx) {
+			return ensureProxy(runtime, ctx);
+		},
+	};
+	return runtime;
+}
+
+async function updateHealthState(runtime: HeadroomRuntime, signal?: AbortSignal): Promise<boolean> {
+	if (isRemoteBlocked(runtime.config)) return false;
+	runtime.state.proxyOnline = await runtime.client.health(signal);
+	return runtime.state.proxyOnline;
+}
+
+async function ensureProxy(runtime: HeadroomRuntime, ctx: ExtensionContext): Promise<boolean> {
+	if (await runtime.updateHealth(ctx)) return true;
+	if (!runtime.config.autoStart || runtime.state.proxyStartAttempted) return false;
+
+	runtime.state.proxyStartAttempted = true;
+	runtime.state.proxyStarting = true;
+	runtime.refreshStatus(ctx);
+	const started = await startPersistentHeadroomProxy(runtime.config);
+	if (!started.ok) {
+		runtime.state.stats.lastError = started.reason;
+		runtime.state.proxyStarting = false;
+		runtime.state.proxyOnline = false;
+		runtime.refreshStatus(ctx);
+		return false;
+	}
+
+	const online = await waitForProxyHealth(runtime, ctx.signal);
+	runtime.state.proxyStarting = false;
+	runtime.state.proxyOnline = online;
+	runtime.refreshStatus(ctx);
+	return online;
+}
+
+async function ensureProxyInBackground(runtime: HeadroomRuntime, ctx?: ExtensionContext): Promise<void> {
+	try {
+		if (await updateHealthState(runtime)) {
+			safeRefreshStatus(runtime, ctx);
+			return;
+		}
+		if (!runtime.config.autoStart || runtime.state.proxyStartAttempted) {
+			safeRefreshStatus(runtime, ctx);
+			return;
+		}
+		runtime.state.proxyStartAttempted = true;
+		runtime.state.proxyStarting = true;
+		safeRefreshStatus(runtime, ctx);
+		const started = await startPersistentHeadroomProxy(runtime.config);
+		if (!started.ok) {
+			runtime.state.stats.lastError = started.reason;
+			runtime.state.proxyStarting = false;
+			runtime.state.proxyOnline = false;
+			safeRefreshStatus(runtime, ctx);
+			return;
+		}
+		runtime.state.proxyOnline = await waitForProxyHealth(runtime);
+		runtime.state.proxyStarting = false;
+		safeRefreshStatus(runtime, ctx);
+	} catch (error) {
+		runtime.state.proxyStarting = false;
+		runtime.state.proxyOnline = false;
+		runtime.state.stats.lastError = error instanceof Error ? error.message : String(error);
+		safeRefreshStatus(runtime, ctx);
+	}
+}
+
+function safeRefreshStatus(runtime: HeadroomRuntime, ctx: ExtensionContext | undefined): void {
+	if (!ctx) return;
+	try {
+		runtime.refreshStatus(ctx);
+	} catch {
+		// The session may have been reloaded/replaced while background health was in flight.
+	}
+}
+
+async function waitForProxyHealth(runtime: HeadroomRuntime, signal?: AbortSignal): Promise<boolean> {
+	for (const delay of [300, 500, 800, 1200, 2000]) {
+		await sleep(delay);
+		if (await updateHealthState(runtime, signal)) return true;
+	}
+	return false;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function handleContextCompression(
+	runtime: HeadroomRuntime,
+	event: ContextEvent,
+	ctx: ExtensionContext,
+): Promise<{ messages?: AgentMessage[] } | undefined> {
+	if (shouldSkipBeforePayload(runtime, ctx)) return undefined;
+	const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
+	if (payload.candidateCount === 0) return undefined;
+	if (runtime.state.proxyOnline !== true) {
+		void ensureProxyInBackground(runtime, ctx);
+		return undefined;
+	}
+
+	runtime.state.stats.attempts++;
+	try {
+		const result = await runtime.client.compress(payload.messages, ctx.model?.id, ctx.signal);
+		runtime.state.proxyOnline = true;
+		if (!result.compressed || result.tokensSaved <= 0) {
+			runtime.refreshStatus(ctx);
+			return undefined;
+		}
+
+		const applied = applyCompressionResult(event.messages, payload.mappings, result.messages, {
+			minMessageChars: runtime.config.minMessageChars,
+		});
+		if (!applied.ok) {
+			recordGuardSkip(runtime.state.stats, applied.reason);
+			runtime.refreshStatus(ctx);
+			return undefined;
+		}
+
+		recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+		runtime.refreshStatus(ctx);
+		return { messages: applied.messages };
+	} catch (error) {
+		recordCompressionError(runtime, ctx, error);
+		return undefined;
+	}
+}
+
+function shouldSkipBeforePayload(runtime: HeadroomRuntime, ctx: ExtensionContext): boolean {
+	if (!runtime.state.enabled) return true;
+	if (isRemoteBlocked(runtime.config)) {
+		if (!runtime.state.remoteWarningShown) {
+			runtime.state.remoteWarningShown = true;
+			ctx.ui.notify("Headroom compression skipped because remote proxy is blocked.", "warning");
+		}
+		runtime.refreshStatus(ctx);
+		return true;
+	}
+	const usage = ctx.getContextUsage();
+	return usage?.tokens !== null && usage?.tokens !== undefined && usage.tokens < runtime.config.minContextTokens;
+}
+
+function recordGuardSkip(stats: HeadroomStats, reason: string): void {
+	stats.guardSkips++;
+	stats.lastSkipReason = reason;
+}
+
+function recordAppliedCompression(stats: HeadroomStats, result: CompressResult, appliedMessages: number): void {
+	stats.applied++;
+	stats.tokensSaved += result.tokensSaved;
+	stats.lastError = undefined;
+	stats.lastSkipReason = undefined;
+	stats.last = { ...result, appliedMessages };
+}
+
+function recordCompressionError(runtime: HeadroomRuntime, ctx: ExtensionContext, error: unknown): void {
+	runtime.state.proxyOnline = false;
+	runtime.state.stats.lastError = error instanceof Error ? error.message : String(error);
+	if (!runtime.state.offlineWarningShown) {
+		runtime.state.offlineWarningShown = true;
+		ctx.ui.notify(
+			`Headroom proxy unavailable. Compression disabled until /headroom health succeeds.\n${runtime.state.stats.lastError}`,
+			"warning",
+		);
+	}
+	runtime.refreshStatus(ctx);
+}
+
+async function handleCommand(runtime: HeadroomRuntime, command: Subcommand, ctx: ExtensionContext): Promise<void> {
+	if (command === "on") {
+		runtime.state.enabled = true;
+		runtime.state.offlineWarningShown = false;
+		runtime.state.proxyStartAttempted = false;
+		const healthy = await runtime.ensureProxy(ctx);
+		ctx.ui.notify(
+			healthy
+				? "Headroom compression enabled. Proxy will keep running after Pi exits."
+				: proxyStartHint(runtime.config),
+			healthy ? "info" : "warning",
+		);
+		return;
+	}
+	if (command === "off") {
+		runtime.state.enabled = false;
+		runtime.refreshStatus(ctx);
+		ctx.ui.notify("Headroom compression disabled for this Pi session. The proxy process is left running.", "info");
+		return;
+	}
+	if (command === "health") {
+		runtime.state.proxyStartAttempted = false;
+		const healthy = await runtime.ensureProxy(ctx);
+		ctx.ui.notify(
+			healthy ? `Headroom proxy online: ${runtime.config.baseUrl}` : proxyStartHint(runtime.config),
+			healthy ? "info" : "warning",
+		);
+		return;
+	}
+	if (command === "stats") {
+		await showProxyStats(ctx, runtime.client, runtime.config);
+		return;
+	}
+	ctx.ui.notify(renderStatus(runtime.config, runtime.state), "info");
+}
+
+function refreshStatus(ctx: ExtensionContext, config: HeadroomConfig, state: HeadroomRuntimeState): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.setStatus(STATUS_KEY, renderFooterStatus(ctx, config, state));
+}
+
+function renderFooterStatus(ctx: ExtensionContext, config: HeadroomConfig, state: HeadroomRuntimeState): string {
+	const theme = ctx.ui.theme;
+	if (!state.enabled) return theme.fg("dim", "○ Headroom off");
+	if (isRemoteBlocked(config)) return theme.fg("warning", "⚠") + theme.fg("dim", " Headroom remote blocked");
+	if (state.proxyStarting) return theme.fg("dim", "⏳ Headroom starting");
+	if (state.proxyOnline === false) return theme.fg("dim", "○ Headroom not running");
+	if (state.proxyOnline === null && !state.stats.last) return theme.fg("dim", "○ Headroom idle");
+	if (!state.stats.last) return theme.fg("success", "✓") + theme.fg("dim", " Headroom");
+
+	const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
+	return (
+		theme.fg("success", "✓") +
+		theme.fg("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`)
+	);
+}
+
+async function showProxyStats(
+	ctx: ExtensionContext,
+	client: HeadroomHttpClient,
+	config: HeadroomConfig,
+): Promise<void> {
+	if (isRemoteBlocked(config)) {
+		ctx.ui.notify(renderRemoteBlocked(config), "warning");
+		return;
+	}
+	try {
+		const stats = await client.stats(ctx.signal);
+		ctx.ui.notify(
+			`Headroom proxy stats (${config.baseUrl}):\n${JSON.stringify(stats, null, 2).slice(0, 4000)}`,
+			"info",
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Could not read Headroom stats: ${message}`, "warning");
+	}
+}
+
+function renderStatus(config: HeadroomConfig, state: HeadroomRuntimeState): string {
+	const stats = state.stats;
+	const lines = [
+		"Headroom token compression",
+		`  Enabled: ${state.enabled ? "yes" : "no"}`,
+		`  Proxy:   ${config.baseUrl} (${state.proxyOnline === true ? "online" : state.proxyStarting ? "starting" : state.proxyOnline === false ? "not running" : "unknown"})`,
+		`  Auto-start: ${config.autoStart ? `yes (${config.command})` : "no"}`,
+		`  Shutdown: proxy is left running after Pi exits`,
+		`  Remote:  ${isRemoteBlocked(config) ? "blocked" : config.allowRemote ? "allowed" : "local-only"}`,
+		`  Thresholds: context >= ${config.minContextTokens.toLocaleString()} tokens, toolResult >= ${config.minMessageChars.toLocaleString()} chars`,
+		"",
+		"Session stats:",
+		`  Attempts:     ${stats.attempts}`,
+		`  Applied:      ${stats.applied}`,
+		`  Guard skips:  ${stats.guardSkips}`,
+		`  Tokens saved: ${stats.tokensSaved.toLocaleString()}`,
+	];
+	if (stats.last) {
+		const pct = Math.round((1 - stats.last.compressionRatio) * 100);
+		lines.push(
+			"",
+			"Last applied compression:",
+			`  ${stats.last.tokensBefore.toLocaleString()} → ${stats.last.tokensAfter.toLocaleString()} tokens (-${pct}%)`,
+			`  Applied messages: ${stats.last.appliedMessages}`,
+			`  Transforms: ${stats.last.transformsApplied.join(", ") || "none"}`,
+			`  CCR hashes: ${stats.last.ccrHashes.length}`,
+		);
+	}
+	if (stats.lastSkipReason) lines.push("", `Last guard skip: ${stats.lastSkipReason}`);
+	if (stats.lastError) lines.push("", `Last error: ${stats.lastError}`);
+	return lines.join("\n");
+}
+
+function proxyStartHint(config: HeadroomConfig): string {
+	if (isRemoteBlocked(config)) return renderRemoteBlocked(config);
+	if (!config.autoStart) {
+		return [
+			`Headroom proxy is not running: ${config.baseUrl}`,
+			"Auto-start is disabled. Start it manually:",
+			`  HEADROOM_TELEMETRY=off ${renderManualProxyCommand(config)}`,
+		].join("\n");
+	}
+	return [
+		`Headroom proxy is not running: ${config.baseUrl}`,
+		`Tried to start persistent proxy with command: ${config.command}`,
+		"Install Headroom or set PI_HEADROOM_COMMAND if needed:",
+		'  pip install "headroom-ai[proxy]"',
+		"  # then run /headroom on",
+	].join("\n");
+}
+
+function renderManualProxyCommand(config: HeadroomConfig): string {
+	try {
+		const url = new URL(config.baseUrl);
+		const host = url.hostname === "localhost" ? "127.0.0.1" : url.hostname.replace(/^\[(.*)]$/, "$1");
+		const port = url.port || "8788";
+		return `${config.command} proxy --host ${host} --port ${port} --mode token --no-cache`;
+	} catch {
+		return `${config.command} proxy --mode token --no-cache`;
+	}
+}
+
+function renderRemoteBlocked(config: HeadroomConfig): string {
+	return [
+		`Headroom remote URL is blocked: ${config.baseUrl}`,
+		"Compression sends conversation context to the proxy.",
+		"Set PI_HEADROOM_ALLOW_REMOTE=1 only for a trusted proxy.",
+	].join("\n");
+}
+
+function parseSubcommand(args: string): Subcommand {
+	const normalized = args.trim().toLowerCase();
+	return SUBCOMMANDS.includes(normalized as Subcommand) ? (normalized as Subcommand) : "status";
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ryan_nookpi/pi-extension-headroom",
+  "version": "0.1.0",
+  "description": "Headroom token compression for pi — compress large tool results via a local Headroom proxy to reclaim context window.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/headroom"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/headroom#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "index.ts",
+    "types.ts",
+    "config.ts",
+    "bridge.ts",
+    "client.ts",
+    "proxy-manager.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/proxy-manager.ts

@@ -0,0 +1,58 @@
+import { execFile, spawn } from "node:child_process";
+import type { HeadroomConfig } from "./types.ts";
+
+export interface ProxyEndpoint {
+	host: string;
+	port: string;
+}
+
+export async function startPersistentHeadroomProxy(
+	config: HeadroomConfig,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+	const endpoint = parseLocalEndpoint(config.baseUrl);
+	if (!endpoint) return { ok: false, reason: "unsupported-local-url" };
+
+	const available = await isCommandAvailable(config.command);
+	if (!available) return { ok: false, reason: `command-not-found:${config.command}` };
+
+	try {
+		const child = spawn(config.command, buildProxyArgs(endpoint), {
+			detached: true,
+			stdio: "ignore",
+			env: {
+				...process.env,
+				HEADROOM_TELEMETRY: process.env.HEADROOM_TELEMETRY || "off",
+			},
+		});
+		child.unref();
+		return { 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"];
+}
+
+export function parseLocalEndpoint(baseUrl: string): ProxyEndpoint | undefined {
+	try {
+		const url = new URL(baseUrl);
+		if (!["http:", "https:"].includes(url.protocol)) 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";
+		return { host, port };
+	} catch {
+		return undefined;
+	}
+}
+
+function isCommandAvailable(command: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = execFile(command, ["--help"], { timeout: 1500 }, (error) => {
+			resolve(!error);
+		});
+		child.on("error", () => resolve(false));
+	});
+}

package/types.ts

@@ -0,0 +1,109 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+// AgentMessage lives in @earendil-works/pi-agent-core, which is only a transitive
+// dependency here. Derive it from the publicly exported ContextEvent payload so the
+// package depends solely on @earendil-works/pi-coding-agent + @earendil-works/pi-ai.
+export type AgentMessage = ContextEvent["messages"][number];
+
+export interface TextContentPart {
+	type: "text";
+	text: string;
+}
+
+export interface ImageContentPart {
+	type: "image_url";
+	image_url: { url: string; detail?: "auto" | "low" | "high" };
+}
+
+export type OpenAIContentPart = TextContentPart | ImageContentPart;
+
+export interface OpenAISystemMessage {
+	role: "system";
+	content: string;
+}
+
+export interface OpenAIUserMessage {
+	role: "user";
+	content: string | OpenAIContentPart[];
+}
+
+export interface OpenAIToolCall {
+	id: string;
+	type: "function";
+	function: { name: string; arguments: string };
+}
+
+export interface OpenAIAssistantMessage {
+	role: "assistant";
+	content: string | null;
+	tool_calls?: OpenAIToolCall[];
+}
+
+export interface OpenAIToolMessage {
+	role: "tool";
+	content: string;
+	tool_call_id: string;
+}
+
+export type OpenAIMessage = OpenAISystemMessage | OpenAIUserMessage | OpenAIAssistantMessage | OpenAIToolMessage;
+
+export interface CompressResult {
+	messages: OpenAIMessage[];
+	tokensBefore: number;
+	tokensAfter: number;
+	tokensSaved: number;
+	compressionRatio: number;
+	transformsApplied: string[];
+	ccrHashes: string[];
+	compressed: boolean;
+}
+
+export interface HeadroomConfig {
+	enabled: boolean;
+	baseUrl: string;
+	allowRemote: boolean;
+	autoStart: boolean;
+	command: string;
+	minContextTokens: number;
+	minMessageChars: number;
+	timeoutMs: number;
+}
+
+export interface HeadroomStats {
+	attempts: number;
+	applied: number;
+	guardSkips: number;
+	tokensSaved: number;
+	last?: {
+		tokensBefore: number;
+		tokensAfter: number;
+		tokensSaved: number;
+		compressionRatio: number;
+		transformsApplied: string[];
+		ccrHashes: string[];
+		appliedMessages: number;
+	};
+	lastError?: string;
+	lastSkipReason?: string;
+}
+
+export interface CompressionMapping {
+	sourceIndex: number;
+	message: OpenAIMessage;
+	applyTo: "toolResult" | null;
+	originalText: string;
+}
+
+export interface CompressionPayload {
+	messages: OpenAIMessage[];
+	mappings: CompressionMapping[];
+	candidateCount: number;
+}
+
+export interface ApplyCompressionOptions {
+	minMessageChars: number;
+}
+
+export type ApplyCompressionResult =
+	| { ok: true; messages: AgentMessage[]; appliedMessages: number }
+	| { ok: false; reason: string };