pi-headroom 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# pi-headroom
+
+Transparent LLM context compression for [Pi](https://github.com/mariozechner/pi-coding-agent) using [Headroom](https://github.com/chopratejas/headroom). Automatically compresses conversation context before every LLM call, saving 70–95% of tokens without changing your workflow.
+
+**Zero-config:** The extension automatically installs the Headroom proxy (`pip install headroom-ai[proxy]`), starts it on session start, and stops it on exit. You don't need to touch the proxy manually.
+
+## How It Works
+
+```
+Session start → auto-install headroom-ai[proxy] → spawn proxy on :8787
+                                                          ↓
+User prompt → Pi builds context → pi-headroom compresses → LLM receives compressed context
+                                                          ↓
+Session exit → proxy stopped automatically
+```
+
+1. **`session_start`**: Checks if proxy is running. If not, installs `headroom-ai[proxy]` via pip (if needed), spawns it as a background process, and polls until healthy.
+2. **`context` event**: Before every LLM call, converts Pi messages to OpenAI format, sends them to the proxy for compression, converts back, and returns compressed messages.
+3. **`session_shutdown`**: Gracefully stops the proxy (only if the extension started it).
+
+## Prerequisites
+
+- **Python ≥ 3.10** — needed to run the Headroom proxy (the extension auto-installs it via pip)
+
+That's it. The extension handles everything else.
+
+## Installation
+
+```bash
+# From local path (development)
+pi install ./pi-headroom
+
+# From npm (once published)
+pi install npm:pi-headroom
+
+# Quick test without installing
+pi -e ./pi-headroom
+```
+
+## Configuration
+
+| Env Variable     | Default                 | Description                                                |
+|------------------|-------------------------|------------------------------------------------------------|
+| `HEADROOM_URL`   | _(none)_                | Set to use your own proxy. **Disables auto-management.**   |
+| `HEADROOM_PORT`  | `8787`                  | Port for the auto-managed proxy                            |
+
+### Auto-management vs. manual mode
+
+- **No env vars set** (default): The extension auto-installs, auto-starts, and auto-stops the proxy. Zero-config.
+- **`HEADROOM_URL` set**: The extension skips auto-management and health-checks the URL you provide. You manage the proxy yourself.
+- **`HEADROOM_PORT` set**: The auto-managed proxy starts on your chosen port instead of 8787.
+
+## Commands
+
+### `/headroom [on|off|status]`
+
+Toggle compression or show status.
+
+- `/headroom` or `/headroom status` — Show current state, proxy mode, and session compression stats
+- `/headroom on` — Enable compression (auto-starts proxy if needed)
+- `/headroom off` — Disable compression (passthrough mode)
+
+### `/headroom-health`
+
+Check proxy health and show diagnostics. Shows whether the proxy is managed by the extension or external.
+
+## Status Bar
+
+The extension shows progress and compression status in Pi's footer:
+
+- `⏳ Installing headroom-ai...` — Auto-installing the proxy
+- `⏳ Starting Headroom proxy...` — Spawning the proxy
+- `✓ Headroom` — Proxy online, ready to compress
+- `✓ Headroom -42% (1,234 saved)` — Last compression result
+- `⚠ Headroom offline` — Proxy unavailable, using uncompressed context
+- `○ Headroom off` — Compression disabled by user
+
+## Behavior
+
+- **Zero-config**: Installs and starts the proxy automatically on first use
+- **Smart detection**: Won't reinstall or restart if already running (e.g., you started it manually)
+- **Graceful fallback**: If anything fails, Pi continues with uncompressed context
+- **Crash recovery**: If the proxy crashes mid-session, one automatic restart is attempted
+- **Clean shutdown**: The proxy is stopped on session exit (only if the extension started it)
+- **Cross-platform**: Works on macOS, Linux, and Windows
+
+## Architecture
+
+```
+pi-headroom/
+├── package.json          # Pi package manifest
+├── tsconfig.json
+├── src/
+│   ├── index.ts          # Extension: context hook, lifecycle, commands
+│   ├── format-bridge.ts  # Pi-AI ↔ OpenAI message format conversion
+│   └── proxy-manager.ts  # Auto-install, start, stop, health check
+└── README.md
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-headroom",
+  "version": "0.1.0",
+  "description": "Transparent LLM context compression for Pi using Headroom",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "headroom-ai": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}

package/src/format-bridge.ts

@@ -0,0 +1,326 @@
+/**
+ * Format bridge between Pi-AI Message[] and Headroom OpenAI message format.
+ *
+ * Pi-AI types:
+ *   UserMessage    { role: "user", content: string | (TextContent | ImageContent)[], timestamp }
+ *   AssistantMessage { role: "assistant", content: (TextContent | ThinkingContent | ToolCall)[], api, provider, model, usage, stopReason, timestamp, ... }
+ *   ToolResultMessage { role: "toolResult", toolCallId, toolName, content: (TextContent | ImageContent)[], details?, isError, timestamp }
+ *
+ * Headroom OpenAI types:
+ *   SystemMessage   { role: "system", content: string }
+ *   UserMessage     { role: "user", content: string | ContentPart[] }
+ *   AssistantMessage { role: "assistant", content: string | null, tool_calls?: ToolCall[] }
+ *   ToolMessage     { role: "tool", content: string, tool_call_id: string }
+ */
+
+import type {
+  Message,
+  UserMessage as PiUserMessage,
+  AssistantMessage as PiAssistantMessage,
+  ToolResultMessage as PiToolResultMessage,
+  TextContent,
+  ImageContent,
+  ToolCall as PiToolCall,
+} from "@mariozechner/pi-ai";
+
+import type {
+  OpenAIMessage,
+  ToolCall as OpenAIToolCall,
+} from "headroom-ai";
+
+// ─── Pi-AI → OpenAI ────────────────────────────────────────────────────
+
+/**
+ * Convert Pi-AI Message[] to Headroom OpenAI format.
+ *
+ * - Strips ThinkingContent from assistant messages (opaque/encrypted, not useful for compression)
+ * - Serializes Pi tool call arguments (Record<string,any>) to JSON strings
+ * - Converts Pi ImageContent (base64) to OpenAI image_url content parts
+ */
+export function piToOpenAI(messages: Message[]): OpenAIMessage[] {
+  const result: OpenAIMessage[] = [];
+
+  for (const msg of messages) {
+    switch (msg.role) {
+      case "user":
+        result.push(convertUserMessage(msg));
+        break;
+      case "assistant":
+        result.push(convertAssistantMessage(msg));
+        break;
+      case "toolResult":
+        result.push(convertToolResultMessage(msg));
+        break;
+    }
+  }
+
+  return result;
+}
+
+function convertUserMessage(msg: PiUserMessage): OpenAIMessage {
+  if (typeof msg.content === "string") {
+    return { role: "user", content: msg.content };
+  }
+
+  // Check if there are any images
+  const hasImages = msg.content.some((part) => part.type === "image");
+
+  if (!hasImages) {
+    // Text-only: join into a single string
+    const text = msg.content
+      .filter((p): p is TextContent => p.type === "text")
+      .map((p) => p.text)
+      .join("\n");
+    return { role: "user", content: text };
+  }
+
+  // Mixed content: convert to OpenAI content parts
+  const parts: Array<{ type: "text"; text: string } | { type: "image_url"; image_url: { url: string } }> = [];
+  for (const part of msg.content) {
+    if (part.type === "text") {
+      parts.push({ type: "text", text: part.text });
+    } else if (part.type === "image") {
+      const imgPart = part as ImageContent;
+      parts.push({
+        type: "image_url",
+        image_url: { url: `data:${imgPart.mimeType};base64,${imgPart.data}` },
+      });
+    }
+  }
+  return { role: "user", content: parts as any };
+}
+
+function convertAssistantMessage(msg: PiAssistantMessage): OpenAIMessage {
+  // Extract text parts (skip ThinkingContent)
+  const textParts = msg.content.filter((p): p is TextContent => p.type === "text");
+  const text = textParts.map((p) => p.text).join("");
+
+  // Extract tool calls
+  const toolCalls = msg.content.filter((p): p is PiToolCall => p.type === "toolCall");
+
+  const openaiMsg: any = {
+    role: "assistant",
+    content: text || null,
+  };
+
+  if (toolCalls.length > 0) {
+    openaiMsg.tool_calls = toolCalls.map(
+      (tc): OpenAIToolCall => ({
+        id: tc.id,
+        type: "function",
+        function: {
+          name: tc.name,
+          arguments: JSON.stringify(tc.arguments),
+        },
+      }),
+    );
+  }
+
+  return openaiMsg;
+}
+
+function convertToolResultMessage(msg: PiToolResultMessage): OpenAIMessage {
+  const text = msg.content
+    .filter((p): p is TextContent => p.type === "text")
+    .map((p) => p.text)
+    .join("\n");
+
+  return {
+    role: "tool",
+    content: text,
+    tool_call_id: msg.toolCallId,
+  };
+}
+
+// ─── OpenAI → Pi-AI ────────────────────────────────────────────────────
+
+/**
+ * Convert compressed OpenAI messages back to Pi-AI Message[] format.
+ *
+ * Strategy: positional alignment with the original messages.
+ * - If message counts match, copy structural metadata from originals, take text from compressed.
+ * - If counts differ (compression merged/dropped messages), build fresh Pi messages.
+ *
+ * Note: The returned messages are used as a deep copy for a single LLM call,
+ * so losing metadata (timestamps, usage) is acceptable.
+ */
+export function openAIToPi(compressed: OpenAIMessage[], original: Message[]): Message[] {
+  // If counts match, use positional alignment
+  if (compressed.length === original.length) {
+    return compressed.map((compMsg, i) => alignMessage(compMsg, original[i]));
+  }
+
+  // Counts differ: build fresh messages
+  return compressed.map((compMsg) => buildFreshMessage(compMsg));
+}
+
+/**
+ * Align a compressed OpenAI message with its original Pi message,
+ * preserving structural metadata from the original.
+ */
+function alignMessage(comp: OpenAIMessage, orig: Message): Message {
+  switch (comp.role) {
+    case "system":
+    case "user":
+      return alignUserMessage(comp, orig);
+    case "assistant":
+      return alignAssistantMessage(comp, orig);
+    case "tool":
+      return alignToolResultMessage(comp, orig);
+    default:
+      return buildFreshMessage(comp);
+  }
+}
+
+function alignUserMessage(comp: OpenAIMessage & { role: "system" | "user" }, orig: Message): Message {
+  const content = typeof comp.content === "string"
+    ? comp.content
+    : Array.isArray(comp.content)
+      ? (comp.content as any[]).filter((p: any) => p.type === "text").map((p: any) => p.text).join("\n")
+      : "";
+
+  if (orig.role === "user") {
+    return {
+      ...orig,
+      content: [{ type: "text", text: content }],
+    };
+  }
+
+  // Role mismatch: build fresh
+  return {
+    role: "user",
+    content: [{ type: "text", text: content }],
+    timestamp: orig.timestamp ?? Date.now(),
+  };
+}
+
+function alignAssistantMessage(comp: OpenAIMessage & { role: "assistant" }, orig: Message): Message {
+  const contentParts: PiAssistantMessage["content"] = [];
+
+  // Add text content
+  const text = typeof comp.content === "string" ? comp.content : null;
+  if (text) {
+    contentParts.push({ type: "text", text });
+  }
+
+  // Add tool calls
+  if (comp.tool_calls) {
+    for (const tc of comp.tool_calls) {
+      contentParts.push({
+        type: "toolCall",
+        id: tc.id,
+        name: tc.function.name,
+        arguments: safeJsonParse(tc.function.arguments),
+      });
+    }
+  }
+
+  // Preserve thinking content from original if it was an assistant message
+  if (orig.role === "assistant") {
+    const thinkingParts = orig.content.filter((p) => p.type === "thinking");
+    return {
+      ...orig,
+      content: [...thinkingParts, ...contentParts],
+    };
+  }
+
+  // Role mismatch: build fresh
+  return buildFreshAssistantMessage(comp);
+}
+
+function alignToolResultMessage(comp: OpenAIMessage & { role: "tool" }, orig: Message): Message {
+  if (orig.role === "toolResult") {
+    return {
+      ...orig,
+      content: [{ type: "text", text: comp.content }],
+    };
+  }
+
+  // Role mismatch: build fresh
+  return buildFreshToolResultMessage(comp);
+}
+
+// ─── Fresh message builders (when positional alignment fails) ───────────
+
+function buildFreshMessage(comp: OpenAIMessage): Message {
+  switch (comp.role) {
+    case "system":
+    case "user":
+      return buildFreshUserMessage(comp);
+    case "assistant":
+      return buildFreshAssistantMessage(comp);
+    case "tool":
+      return buildFreshToolResultMessage(comp);
+    default:
+      return {
+        role: "user",
+        content: [{ type: "text", text: String((comp as any).content ?? "") }],
+        timestamp: Date.now(),
+      };
+  }
+}
+
+function buildFreshUserMessage(comp: { role: string; content: any }): PiUserMessage {
+  const content = typeof comp.content === "string"
+    ? comp.content
+    : Array.isArray(comp.content)
+      ? (comp.content as any[]).filter((p: any) => p.type === "text").map((p: any) => p.text).join("\n")
+      : "";
+
+  return {
+    role: "user",
+    content: [{ type: "text", text: content }],
+    timestamp: Date.now(),
+  };
+}
+
+function buildFreshAssistantMessage(comp: OpenAIMessage & { role: "assistant" }): PiAssistantMessage {
+  const contentParts: PiAssistantMessage["content"] = [];
+
+  if (typeof comp.content === "string" && comp.content) {
+    contentParts.push({ type: "text", text: comp.content });
+  }
+
+  if (comp.tool_calls) {
+    for (const tc of comp.tool_calls) {
+      contentParts.push({
+        type: "toolCall",
+        id: tc.id,
+        name: tc.function.name,
+        arguments: safeJsonParse(tc.function.arguments),
+      });
+    }
+  }
+
+  return {
+    role: "assistant",
+    content: contentParts,
+    api: "openai-completions",
+    provider: "unknown",
+    model: "unknown",
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+    stopReason: "stop",
+    timestamp: Date.now(),
+  };
+}
+
+function buildFreshToolResultMessage(comp: OpenAIMessage & { role: "tool" }): PiToolResultMessage {
+  return {
+    role: "toolResult",
+    toolCallId: comp.tool_call_id,
+    toolName: "unknown",
+    content: [{ type: "text", text: comp.content }],
+    isError: false,
+    timestamp: Date.now(),
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function safeJsonParse(str: string): Record<string, any> {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return { _raw: str };
+  }
+}

package/src/index.ts

@@ -0,0 +1,341 @@
+/**
+ * pi-headroom — Transparent LLM context compression for Pi using Headroom.
+ *
+ * Hooks into Pi's `context` event to compress messages before every LLM call.
+ * Automatically installs and manages the Headroom proxy (zero-config).
+ *
+ * Set HEADROOM_URL to skip auto-management and use your own proxy.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm } from "@mariozechner/pi-coding-agent";
+import { HeadroomClient, compress } from "headroom-ai";
+import type { CompressResult } from "headroom-ai";
+import { piToOpenAI, openAIToPi } from "./format-bridge.js";
+import { ProxyManager } from "./proxy-manager.js";
+
+export default function headroomExtension(pi: ExtensionAPI) {
+  // ─── State ──────────────────────────────────────────────────────────
+
+  let enabled = true;
+  let proxyAvailable: boolean | null = null;
+  let proxyWarningShown = false;
+  let restartAttempted = false;
+
+  let lastStats: {
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    ratio: number;
+    transforms: string[];
+  } = { tokensBefore: 0, tokensAfter: 0, tokensSaved: 0, ratio: 1.0, transforms: [] };
+
+  let sessionTotals = { calls: 0, tokensSaved: 0 };
+
+  // ─── Configuration ──────────────────────────────────────────────────
+
+  const userUrl = process.env.HEADROOM_URL;
+  const autoManage = !userUrl;
+  const port = parseInt(process.env.HEADROOM_PORT || "8787", 10);
+  const proxyManager = autoManage ? new ProxyManager({ port }) : null;
+  const baseUrl = userUrl || `http://127.0.0.1:${port}`;
+  const client = new HeadroomClient({ baseUrl, fallback: true, timeout: 15_000 });
+
+  /** Simple health check — the SDK doesn't expose one, so we hit the proxy directly. */
+  async function checkProxyHealth(): Promise<boolean> {
+    try {
+      const res = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(5_000) });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  // ─── Session start: install/start proxy or health-check ─────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    proxyWarningShown = false;
+    restartAttempted = false;
+    sessionTotals = { calls: 0, tokensSaved: 0 };
+
+    if (proxyManager) {
+      // Auto-manage mode
+      ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", "⏳ Headroom starting..."));
+
+      const ok = await proxyManager.ensureRunning((msg) => {
+        ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", `⏳ ${msg}`));
+      });
+
+      if (ok) {
+        proxyAvailable = true;
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+        );
+      } else {
+        proxyAvailable = false;
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+        );
+        ctx.ui.notify(
+          "Headroom proxy could not be started. Context compression disabled.\nRun /headroom-health for details.",
+          "warning",
+        );
+      }
+    } else {
+      // User-managed mode: just health-check
+      const healthy = await checkProxyHealth();
+      if (healthy) {
+        proxyAvailable = true;
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+        );
+      } else {
+        proxyAvailable = false;
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+        );
+      }
+    }
+  });
+
+  // ─── Session shutdown: stop proxy if we started it ──────────────────
+
+  pi.on("session_shutdown", async () => {
+    if (proxyManager) {
+      await proxyManager.stop();
+    }
+  });
+
+  // ─── Core: compress context before every LLM call ───────────────────
+
+  pi.on("context", async (event, ctx) => {
+    if (!enabled || proxyAvailable === false) return;
+
+    // Convert AgentMessage[] → Pi-AI Message[] → OpenAI format
+    const piMessages = convertToLlm(event.messages);
+    if (piMessages.length === 0) return;
+
+    const openaiMessages = piToOpenAI(piMessages);
+    if (openaiMessages.length === 0) return;
+
+    try {
+      const result: CompressResult = await compress(openaiMessages, {
+        client,
+        model: ctx.model?.id ?? "gpt-4o",
+        fallback: true,
+      });
+
+      if (!result.compressed || result.tokensSaved <= 0) {
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("success", "✓") +
+            ctx.ui.theme.fg("dim", ` Headroom (${openaiMessages.length} msgs, no compression needed)`),
+        );
+        return;
+      }
+
+      // Convert compressed OpenAI → Pi-AI Message[]
+      const compressedPiMessages = openAIToPi(result.messages, piMessages);
+
+      // Update stats
+      lastStats = {
+        tokensBefore: result.tokensBefore,
+        tokensAfter: result.tokensAfter,
+        tokensSaved: result.tokensSaved,
+        ratio: result.compressionRatio,
+        transforms: result.transformsApplied,
+      };
+      sessionTotals.calls++;
+      sessionTotals.tokensSaved += result.tokensSaved;
+
+      // Update status bar
+      const saved = result.tokensSaved.toLocaleString();
+      const pct = Math.round((1 - result.compressionRatio) * 100);
+      const theme = ctx.ui.theme;
+      ctx.ui.setStatus(
+        "headroom",
+        theme.fg("success", "✓") + theme.fg("dim", ` Headroom -${pct}% (${saved} saved)`),
+      );
+
+      return { messages: compressedPiMessages as any };
+    } catch (error) {
+      if (!proxyWarningShown) {
+        proxyWarningShown = true;
+        proxyAvailable = false;
+
+        const errMsg = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Headroom proxy unavailable: ${errMsg}`, "warning");
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+        );
+      }
+
+      // Mid-session crash recovery (one attempt per session)
+      if (proxyManager && !restartAttempted) {
+        restartAttempted = true;
+        const recovered = await proxyManager.tryRestart((msg) => {
+          ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", `⏳ ${msg}`));
+        });
+        if (recovered) {
+          proxyAvailable = true;
+          proxyWarningShown = false;
+          ctx.ui.setStatus(
+            "headroom",
+            ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+          );
+          // Don't retry compression this call — next context event will use it
+        }
+      }
+
+      return;
+    }
+  });
+
+  // ─── /headroom command — toggle and status ──────────────────────────
+
+  pi.registerCommand("headroom", {
+    description: "Toggle Headroom compression or show status. Usage: /headroom [on|off|status]",
+    handler: async (args, ctx) => {
+      const arg = args.trim().toLowerCase();
+
+      if (arg === "on") {
+        enabled = true;
+        proxyWarningShown = false;
+        restartAttempted = false;
+
+        if (proxyManager) {
+          // Try to start the proxy
+          ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", "⏳ Starting..."));
+          const ok = await proxyManager.ensureRunning((msg) => {
+            ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", `⏳ ${msg}`));
+          });
+          if (ok) {
+            proxyAvailable = true;
+            ctx.ui.notify("Headroom compression enabled", "info");
+            ctx.ui.setStatus(
+              "headroom",
+              ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+            );
+          } else {
+            proxyAvailable = false;
+            ctx.ui.notify("Headroom enabled but proxy could not be started", "warning");
+            ctx.ui.setStatus(
+              "headroom",
+              ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+            );
+          }
+        } else {
+          // User-managed: just health-check
+          const ok2 = await checkProxyHealth();
+          if (ok2) {
+            proxyAvailable = true;
+            ctx.ui.notify("Headroom compression enabled", "info");
+            ctx.ui.setStatus(
+              "headroom",
+              ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+            );
+          } else {
+            proxyAvailable = false;
+            ctx.ui.notify("Headroom enabled but proxy is offline", "warning");
+            ctx.ui.setStatus(
+              "headroom",
+              ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+            );
+          }
+        }
+        return;
+      }
+
+      if (arg === "off") {
+        enabled = false;
+        ctx.ui.notify("Headroom compression disabled", "info");
+        ctx.ui.setStatus("headroom", ctx.ui.theme.fg("dim", "○ Headroom off"));
+        return;
+      }
+
+      // Status (default)
+      const managedStr = proxyManager
+        ? proxyManager.isManaged
+          ? "auto (managed by extension)"
+          : "auto (external proxy detected)"
+        : "manual (HEADROOM_URL set)";
+
+      const lines = [
+        `Headroom Context Compression`,
+        `  Enabled: ${enabled ? "yes" : "no"}`,
+        `  Proxy:   ${baseUrl} (${proxyAvailable === true ? "online" : proxyAvailable === false ? "offline" : "unknown"})`,
+        `  Mode:    ${managedStr}`,
+        ``,
+        `Session stats:`,
+        `  Compressions: ${sessionTotals.calls}`,
+        `  Tokens saved: ${sessionTotals.tokensSaved.toLocaleString()}`,
+      ];
+
+      if (lastStats.tokensBefore > 0) {
+        const pct = Math.round((1 - lastStats.ratio) * 100);
+        lines.push(
+          ``,
+          `Last compression:`,
+          `  ${lastStats.tokensBefore.toLocaleString()} → ${lastStats.tokensAfter.toLocaleString()} tokens (-${pct}%)`,
+          `  Transforms: ${lastStats.transforms.join(", ") || "none"}`,
+        );
+      }
+
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  // ─── /headroom-health command — proxy diagnostics ───────────────────
+
+  pi.registerCommand("headroom-health", {
+    description: "Check Headroom proxy health and show diagnostics",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(`Checking Headroom proxy at ${baseUrl}...`, "info");
+
+      const isHealthy = await checkProxyHealth();
+      if (isHealthy) {
+        proxyAvailable = true;
+
+        const lines = [
+          `Headroom proxy: online`,
+          `  URL: ${baseUrl}`,
+        ];
+
+        if (proxyManager) {
+          lines.push(`  Managed: ${proxyManager.isManaged ? "yes (started by extension)" : "no (external)"}`);
+        }
+
+        ctx.ui.notify(lines.join("\n"), "info");
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("success", "✓") + ctx.ui.theme.fg("dim", " Headroom"),
+        );
+      } else {
+        proxyAvailable = false;
+        const errMsg = "proxy did not respond";
+        const helpLines = [
+          `Headroom proxy offline`,
+          `  URL: ${baseUrl}`,
+          `  Error: ${errMsg}`,
+        ];
+
+        if (proxyManager) {
+          helpLines.push(``, `The extension will auto-start the proxy on next session.`, `Or run: /headroom on`);
+        } else {
+          helpLines.push(``, `Start the proxy manually:`, `  headroom proxy`, `  # or`, `  pip install "headroom-ai[proxy]" && headroom proxy`);
+        }
+
+        ctx.ui.notify(helpLines.join("\n"), "error");
+        ctx.ui.setStatus(
+          "headroom",
+          ctx.ui.theme.fg("warning", "⚠") + ctx.ui.theme.fg("dim", " Headroom offline"),
+        );
+      }
+    },
+  });
+}

package/src/proxy-manager.ts

@@ -0,0 +1,364 @@
+/**
+ * Headroom proxy lifecycle manager.
+ *
+ * Handles: Python detection, venv creation, pip install, background proxy spawn,
+ * health polling, graceful shutdown, and crash recovery.
+ *
+ * Uses a dedicated venv (~/.pi/headroom-venv/) to avoid PEP 668 issues on
+ * macOS/Homebrew and to keep the system Python clean.
+ */
+
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const IS_WINDOWS = process.platform === "win32";
+const VENV_DIR = join(homedir(), ".pi", "headroom-venv");
+const VENV_BIN = IS_WINDOWS ? join(VENV_DIR, "Scripts") : join(VENV_DIR, "bin");
+const VENV_PYTHON = join(VENV_BIN, IS_WINDOWS ? "python.exe" : "python");
+const VENV_HEADROOM = join(VENV_BIN, IS_WINDOWS ? "headroom.exe" : "headroom");
+
+// ─── Python detection ─────────────────────────────────────────────────
+
+/**
+ * Find a Python >=3.10 interpreter. Tries python3 then python.
+ * Returns the command string or null if not found.
+ */
+export async function findPython(): Promise<string | null> {
+  for (const cmd of ["python3", "python"]) {
+    const version = await getPythonVersion(cmd);
+    if (version && version.major >= 3 && version.minor >= 10) {
+      return cmd;
+    }
+  }
+  return null;
+}
+
+async function getPythonVersion(
+  cmd: string,
+): Promise<{ major: number; minor: number } | null> {
+  try {
+    const output = await execAsync(cmd, ["--version"]);
+    // "Python 3.12.4"
+    const match = output.match(/Python (\d+)\.(\d+)/);
+    if (match) {
+      return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+    }
+  } catch {
+    // Command not found or errored
+  }
+  return null;
+}
+
+// ─── Venv + install ───────────────────────────────────────────────────
+
+/**
+ * Ensure the headroom venv exists and headroom-ai[proxy] is installed.
+ * Returns the path to the headroom CLI in the venv, or null on failure.
+ */
+async function ensureVenv(
+  onStatus: (msg: string) => void,
+): Promise<string | null> {
+  // 1. If venv already has headroom, we're done
+  if (existsSync(VENV_HEADROOM)) {
+    return VENV_HEADROOM;
+  }
+
+  // 2. Find system Python
+  const python = await findPython();
+  if (!python) {
+    onStatus("Python >=3.10 not found — cannot install Headroom");
+    return null;
+  }
+
+  // 3. Create venv if it doesn't exist
+  if (!existsSync(VENV_PYTHON)) {
+    onStatus("Creating Headroom venv...");
+    try {
+      await execAsync(python, ["-m", "venv", VENV_DIR], 60_000);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      onStatus(`Failed to create venv: ${msg}`);
+      return null;
+    }
+  }
+
+  // 4. Install headroom-ai[proxy] into the venv
+  onStatus("Installing headroom-ai (this may take a minute)...");
+  try {
+    await execAsync(
+      VENV_PYTHON,
+      ["-m", "pip", "install", "headroom-ai[proxy]", "--quiet", "--disable-pip-version-check"],
+      180_000, // 3 minute timeout — first install downloads many deps
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    onStatus(`pip install failed: ${msg}`);
+    return null;
+  }
+
+  // 5. Verify
+  if (existsSync(VENV_HEADROOM)) {
+    return VENV_HEADROOM;
+  }
+
+  // Fallback: try via python -m
+  try {
+    await execAsync(VENV_PYTHON, ["-m", "headroom.cli", "--help"], 10_000);
+    return null; // CLI binary doesn't exist, but module works — handled separately
+  } catch {
+    // pass
+  }
+
+  onStatus("headroom installed but CLI not found in venv");
+  return null;
+}
+
+/**
+ * Ensure headroom is available. Checks system PATH first, then venv.
+ * Returns the invocation method: { cmd, args } to spawn the proxy,
+ * or null if installation failed.
+ */
+export async function ensureInstalled(
+  onStatus: (msg: string) => void,
+): Promise<{ cmd: string; args: string[] } | null> {
+  // 1. Check if `headroom` CLI is already on system PATH
+  if (await isCommandAvailable("headroom", ["--help"])) {
+    return { cmd: "headroom", args: [] };
+  }
+
+  // 2. Check if venv already has headroom
+  if (existsSync(VENV_HEADROOM) && await isCommandAvailable(VENV_HEADROOM, ["--help"])) {
+    return { cmd: VENV_HEADROOM, args: [] };
+  }
+
+  // 3. Create venv and install
+  const headroomPath = await ensureVenv(onStatus);
+  if (headroomPath) {
+    return { cmd: headroomPath, args: [] };
+  }
+
+  // 4. Fallback: try module invocation in venv
+  if (existsSync(VENV_PYTHON) && await isCommandAvailable(VENV_PYTHON, ["-m", "headroom.cli", "--help"])) {
+    return { cmd: VENV_PYTHON, args: ["-m", "headroom.cli"] };
+  }
+
+  return null;
+}
+
+async function isCommandAvailable(cmd: string, args: string[]): Promise<boolean> {
+  try {
+    await execAsync(cmd, args, 10_000);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── ProxyManager ─────────────────────────────────────────────────────
+
+export class ProxyManager {
+  private proc: ChildProcess | null = null;
+  private weStartedIt = false;
+  private stopping = false;
+  private port: number;
+  private host: string;
+  /** Stored invocation method from ensureInstalled */
+  private invocation: { cmd: string; args: string[] } | null = null;
+
+  constructor(options?: { port?: number; host?: string }) {
+    this.port = options?.port ?? 8787;
+    this.host = options?.host ?? "127.0.0.1";
+  }
+
+  get baseUrl(): string {
+    return `http://${this.host}:${this.port}`;
+  }
+
+  get isManaged(): boolean {
+    return this.weStartedIt;
+  }
+
+  // ── Full lifecycle: detect → install → start → health-check ───────
+
+  async ensureRunning(onStatus: (msg: string) => void): Promise<boolean> {
+    if (this.stopping) return false;
+
+    // 1. Already running? (external or our own)
+    onStatus("Checking for running proxy...");
+    if (await this.healthCheck()) {
+      return true; // Don't touch it — someone else's proxy or our still-alive one
+    }
+
+    // 2. Ensure headroom is installed (venv-based)
+    const invocation = await ensureInstalled(onStatus);
+    if (!invocation) return false;
+    this.invocation = invocation;
+
+    // 3. Spawn proxy
+    this.startProxy(onStatus);
+
+    // 4. Poll for health with backoff
+    const delays = [500, 1000, 1000, 2000, 2000, 2000, 2000, 2000];
+    for (const delay of delays) {
+      if (this.stopping) return false;
+      await sleep(delay);
+
+      // If process exited already, bail early
+      if (this.proc && this.proc.exitCode !== null) {
+        onStatus("Headroom proxy exited unexpectedly");
+        this.proc = null;
+        return false;
+      }
+
+      if (await this.healthCheck()) {
+        this.weStartedIt = true;
+        return true;
+      }
+    }
+
+    // 5. Timed out — kill and report failure
+    onStatus("Headroom proxy failed to start (health check timeout)");
+    this.killProcess();
+    return false;
+  }
+
+  // ── Health check ──────────────────────────────────────────────────
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/health`, {
+        signal: AbortSignal.timeout(3000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── Stop proxy (if we started it) ─────────────────────────────────
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+
+    if (!this.proc || !this.weStartedIt) {
+      this.proc = null;
+      this.weStartedIt = false;
+      return;
+    }
+
+    const proc = this.proc;
+    this.proc = null;
+    this.weStartedIt = false;
+
+    // Send SIGTERM (or hard-kill on Windows)
+    try {
+      if (IS_WINDOWS) {
+        proc.kill();
+      } else {
+        proc.kill("SIGTERM");
+
+        // Wait up to 3s for graceful exit
+        const exited = await Promise.race([
+          new Promise<boolean>((resolve) => {
+            proc.on("exit", () => resolve(true));
+          }),
+          sleep(3000).then(() => false),
+        ]);
+
+        if (!exited && proc.exitCode === null) {
+          proc.kill("SIGKILL");
+        }
+      }
+    } catch {
+      // Process may already be dead
+    }
+  }
+
+  // ── Crash recovery ────────────────────────────────────────────────
+
+  /**
+   * Try to restart the proxy once if it crashed.
+   * Returns true if recovered.
+   */
+  async tryRestart(onStatus: (msg: string) => void): Promise<boolean> {
+    if (!this.weStartedIt) return false;
+    if (this.proc && this.proc.exitCode === null) return false; // still running
+
+    onStatus("Headroom proxy crashed, restarting...");
+    this.proc = null;
+    this.weStartedIt = false;
+    this.stopping = false;
+    return this.ensureRunning(onStatus);
+  }
+
+  // ── Private: spawn the proxy ──────────────────────────────────────
+
+  private startProxy(onStatus: (msg: string) => void): void {
+    onStatus("Starting Headroom proxy...");
+
+    const inv = this.invocation;
+    if (!inv) return;
+
+    // Build args: e.g. ["proxy", "--port", "8787", "--host", "127.0.0.1"]
+    // or ["-m", "headroom.cli", "proxy", "--port", "8787", ...]
+    const spawnArgs = [...inv.args, "proxy", "--port", String(this.port), "--host", this.host];
+
+    const proc = spawn(inv.cmd, spawnArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+      env: { ...process.env },
+    });
+
+    proc.on("error", () => {
+      // spawn error (e.g. command not found) — don't crash
+    });
+
+    proc.on("exit", () => {
+      if (this.proc === proc) {
+        this.proc = null;
+        this.weStartedIt = false;
+      }
+    });
+
+    // Unref streams so they don't keep the event loop alive on shutdown
+    (proc.stdout as any)?.unref?.();
+    (proc.stderr as any)?.unref?.();
+
+    this.proc = proc;
+  }
+
+  private killProcess(): void {
+    if (this.proc) {
+      try {
+        this.proc.kill(IS_WINDOWS ? undefined : "SIGKILL");
+      } catch {
+        // Already dead
+      }
+      this.proc = null;
+    }
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function execAsync(
+  cmd: string,
+  args: string[],
+  timeoutMs = 15_000,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr || error.message));
+      } else {
+        resolve((stdout || "") + (stderr || ""));
+      }
+    });
+  });
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}