@raquezha/noheadroom 0.0.2

package/dist/index.js

@@ -0,0 +1,431 @@
+import { Box, Text } from "@earendil-works/pi-tui";
+import { applyCompressionResult, buildCompressionPayload } from "./bridge.js";
+import { HeadroomHttpClient } from "./client.js";
+import { isRemoteBlocked, loadHeadroomConfig } from "./config.js";
+import { startPersistentHeadroomProxy } from "./proxy-manager.js";
+const STATUS_KEY = "headroom";
+const SUBCOMMANDS = ["status", "on", "off", "health", "stats"];
+const COMPRESSION_ENTRY_TYPE = "noheadroom.compression";
+export default function headroomExtension(pi) {
+    registerCompressionRenderer(pi);
+    const runtime = createRuntime(pi);
+    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(pi) {
+    const config = loadHeadroomConfig();
+    const client = new HeadroomHttpClient({ baseUrl: config.baseUrl, timeoutMs: config.timeoutMs });
+    const state = {
+        enabled: config.enabled,
+        proxyOnline: null,
+        proxyStarting: false,
+        proxyStartAttempted: false,
+        remoteWarningShown: false,
+        offlineWarningShown: false,
+        stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
+    };
+    const runtime = {
+        pi,
+        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, signal) {
+    if (isRemoteBlocked(runtime.config))
+        return false;
+    runtime.state.proxyOnline = await runtime.client.health(signal);
+    return runtime.state.proxyOnline;
+}
+async function ensureProxy(runtime, ctx) {
+    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, ctx) {
+    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, ctx) {
+    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, signal) {
+    for (const delay of [300, 500, 800, 1200, 2000]) {
+        await sleep(delay);
+        if (await updateHealthState(runtime, signal))
+            return true;
+    }
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function registerCompressionRenderer(pi) {
+    pi.registerMessageRenderer(COMPRESSION_ENTRY_TYPE, (message, { expanded }, theme) => {
+        const details = message.details;
+        const content = typeof message.content === "string" ? message.content : "noheadroom compression applied";
+        const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+        let text = `${theme.fg("success", "🗜 noheadroom")} ${content}`;
+        if (expanded && details) {
+            text += `\n${theme.fg("dim", `  before: ${details.tokensBefore.toLocaleString()} tokens`)}`;
+            text += `\n${theme.fg("dim", `  after:  ${details.tokensAfter.toLocaleString()} tokens`)}`;
+            text += `\n${theme.fg("dim", `  saved:  ${details.tokensSaved.toLocaleString()} tokens`)}`;
+            text += `\n${theme.fg("dim", `  messages: ${details.appliedMessages}`)}`;
+            text += `\n${theme.fg("dim", `  transforms: ${details.transformsApplied.join(", ") || "none"}`)}`;
+        }
+        box.addChild(new Text(text, 0, 0));
+        return box;
+    });
+}
+async function handleContextCompression(runtime, event, ctx) {
+    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);
+            announceGuardSkip(ctx, applied.reason, result);
+            runtime.refreshStatus(ctx);
+            return undefined;
+        }
+        recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+        announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages);
+        runtime.refreshStatus(ctx);
+        return { messages: applied.messages };
+    }
+    catch (error) {
+        recordCompressionError(runtime, ctx, error);
+        return undefined;
+    }
+}
+function shouldSkipBeforePayload(runtime, ctx) {
+    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, reason) {
+    stats.guardSkips++;
+    stats.lastSkipReason = reason;
+}
+function recordAppliedCompression(stats, result, appliedMessages) {
+    stats.applied++;
+    stats.tokensSaved += result.tokensSaved;
+    stats.lastError = undefined;
+    stats.lastSkipReason = undefined;
+    stats.last = { ...result, appliedMessages };
+}
+function announceAppliedCompression(pi, ctx, result, appliedMessages) {
+    const pct = Math.round((1 - result.compressionRatio) * 100);
+    const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
+    const line = `noheadroom: ${summary}`;
+    ctx.ui.notify(line, "info");
+    pi.sendMessage({
+        customType: COMPRESSION_ENTRY_TYPE,
+        content: summary,
+        display: true,
+        details: {
+            tokensBefore: result.tokensBefore,
+            tokensAfter: result.tokensAfter,
+            tokensSaved: result.tokensSaved,
+            compressionRatio: result.compressionRatio,
+            appliedMessages,
+            transformsApplied: result.transformsApplied,
+            timestamp: Date.now(),
+        },
+    });
+    // Non-interactive `pi -p` does not always show footer/status UI, so print an explicit proof line.
+    process.stderr.write(`🗜 ${line}\n`);
+}
+function announceGuardSkip(ctx, reason, result) {
+    const line = `noheadroom: compression skipped by guard (${reason}); Headroom reported ${result.tokensSaved.toLocaleString()} tokens saved but Pi context was left unchanged`;
+    ctx.ui.notify(line, "warning");
+    process.stderr.write(`⚠ ${line}\n`);
+}
+function recordCompressionError(runtime, ctx, error) {
+    runtime.state.stats.lastError = getErrorMessage(error);
+    if (isAbortOrTimeoutError(error)) {
+        runtime.refreshStatus(ctx);
+        return;
+    }
+    runtime.state.proxyOnline = false;
+    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);
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isAbortOrTimeoutError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    if (candidate.name === "TimeoutError" || candidate.name === "AbortError")
+        return true;
+    if (typeof candidate.message === "string" &&
+        /aborted due to timeout|operation was aborted/i.test(candidate.message)) {
+        return true;
+    }
+    return candidate.cause !== undefined && candidate.cause !== error && isAbortOrTimeoutError(candidate.cause);
+}
+async function handleCommand(runtime, command, ctx) {
+    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, config, state) {
+    if (!ctx.hasUI)
+        return;
+    ctx.ui.setStatus(STATUS_KEY, renderFooterStatus(ctx, config, state));
+}
+function isHeadroomStatusTheme(theme) {
+    return typeof theme?.fg === "function";
+}
+function createStatusPainter(theme) {
+    if (isHeadroomStatusTheme(theme))
+        return (color, text) => theme.fg(color, text);
+    return (_color, text) => text;
+}
+function renderFooterStatus(ctx, config, state) {
+    const paint = createStatusPainter(ctx.ui.theme);
+    if (!state.enabled)
+        return paint("dim", "○ Headroom off");
+    if (isRemoteBlocked(config))
+        return paint("warning", "⚠") + paint("dim", " Headroom remote blocked");
+    if (state.proxyStarting)
+        return paint("dim", "⏳ Headroom starting");
+    if (state.proxyOnline === false)
+        return paint("dim", "○ Headroom not running");
+    if (state.proxyOnline === null && !state.stats.last)
+        return paint("dim", "○ Headroom idle");
+    if (!state.stats.last)
+        return paint("success", "✓") + paint("dim", " Headroom");
+    const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
+    return (paint("success", "✓") + paint("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`));
+}
+async function showProxyStats(ctx, client, config) {
+    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, state) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const normalized = args.trim().toLowerCase();
+    return SUBCOMMANDS.includes(normalized) ? normalized : "status";
+}
+export const __test__ = {
+    isAbortOrTimeoutError,
+    renderFooterStatus,
+};

package/dist/proxy-manager.d.ts

@@ -0,0 +1,13 @@
+import type { HeadroomConfig } from "./types.js";
+export interface ProxyEndpoint {
+    host: string;
+    port: string;
+}
+export declare function startPersistentHeadroomProxy(config: HeadroomConfig): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function buildProxyArgs(endpoint: ProxyEndpoint): string[];
+export declare function parseLocalEndpoint(baseUrl: string): ProxyEndpoint | undefined;

package/dist/proxy-manager.js

@@ -0,0 +1,50 @@
+import { execFile, spawn } from "node:child_process";
+export async function startPersistentHeadroomProxy(config) {
+    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) {
+    return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "token", "--no-cache"];
+}
+export function parseLocalEndpoint(baseUrl) {
+    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) {
+    return new Promise((resolve) => {
+        const child = execFile(command, ["--help"], { timeout: 1500 }, (error) => {
+            resolve(!error);
+        });
+        child.on("error", () => resolve(false));
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+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;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};