@ryan_nookpi/pi-extension-headroom 0.1.0 → 0.1.2

package/README.md

@@ -43,17 +43,26 @@ The footer shows a compact status (`✓ Headroom -42% (12,345 saved)`) once comp
 
 ## 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`.
+Settings are read at startup from `~/.pi/agent/headroom/settings.json`. Values in this file override environment variables; environment variables remain supported as fallbacks.
+
+Example:
+
+```json
+{
+  "minContextTokens": 10000,
+  "minMessageChars": 1000
+}
+```
+
+| Setting key | Env fallback | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `PI_HEADROOM_ENABLED` | `true` | Enable compression on start. |
+| `baseUrl` (`url` also accepted) | `PI_HEADROOM_URL` (`HEADROOM_URL` / `HEADROOM_BASE_URL` also accepted) | `http://127.0.0.1:8788` | Proxy base URL. |
+| `allowRemote` | `PI_HEADROOM_ALLOW_REMOTE` | `false` | Allow non-local proxy URLs. |
+| `autoStart` | `PI_HEADROOM_AUTO_START` | `true` | Auto-start a local persistent proxy when offline. |
+| `command` | `PI_HEADROOM_COMMAND` | `headroom` | Command used to launch the proxy. |
+| `minContextTokens` | `PI_HEADROOM_MIN_CONTEXT_TOKENS` | `20000` | Skip compression below this context token count. |
+| `minMessageChars` | `PI_HEADROOM_MIN_MESSAGE_CHARS` | `2000` | Only compress tool results at or above this size. |
+| `timeoutMs` | `PI_HEADROOM_TIMEOUT_MS` | `30000` | HTTP timeout for proxy requests. |
+
+Boolean values accept JSON booleans, or strings such as `1/0`, `true/false`, `yes/no`, `on/off`.

package/config.ts

@@ -1,23 +1,62 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 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;
+const DEFAULT_TIMEOUT_MS = 30_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,
-	);
+export const HEADROOM_SETTINGS_DIR = path.join(os.homedir(), ".pi", "agent", "headroom");
+export const HEADROOM_SETTINGS_FILE = path.join(HEADROOM_SETTINGS_DIR, "settings.json");
+
+export interface HeadroomSettings {
+	enabled?: boolean | string;
+	baseUrl?: string;
+	url?: string;
+	allowRemote?: boolean | string;
+	autoStart?: boolean | string;
+	command?: string;
+	minContextTokens?: number | string;
+	minMessageChars?: number | string;
+	timeoutMs?: number | string;
+}
+
+export function loadHeadroomSettings(settingsPath: string = HEADROOM_SETTINGS_FILE): HeadroomSettings {
+	try {
+		const raw = fs.readFileSync(settingsPath, "utf-8");
+		const parsed = JSON.parse(raw) as unknown;
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as HeadroomSettings;
+	} catch {
+		// Missing or invalid settings.json falls back to env/defaults.
+	}
+	return {};
+}
+
+export function loadHeadroomConfig(
+	env: NodeJS.ProcessEnv = process.env,
+	settings: HeadroomSettings = env === process.env ? loadHeadroomSettings() : {},
+): HeadroomConfig {
+	const envBaseUrl = env.PI_HEADROOM_URL || env.HEADROOM_URL || env.HEADROOM_BASE_URL || DEFAULT_BASE_URL;
+	const baseUrl = normalizeBaseUrl(parseString(settings.baseUrl ?? settings.url, envBaseUrl));
 	return {
-		enabled: parseBoolean(env.PI_HEADROOM_ENABLED, true),
+		enabled: parseBoolean(settings.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),
+		allowRemote: parseBoolean(settings.allowRemote, parseBoolean(env.PI_HEADROOM_ALLOW_REMOTE, false)),
+		autoStart: parseBoolean(settings.autoStart, parseBoolean(env.PI_HEADROOM_AUTO_START, true)),
+		command: parseString(settings.command, env.PI_HEADROOM_COMMAND?.trim() || "headroom"),
+		minContextTokens: parseInteger(
+			settings.minContextTokens,
+			parseInteger(env.PI_HEADROOM_MIN_CONTEXT_TOKENS, DEFAULT_MIN_CONTEXT_TOKENS, 0),
+			0,
+		),
+		minMessageChars: parseInteger(
+			settings.minMessageChars,
+			parseInteger(env.PI_HEADROOM_MIN_MESSAGE_CHARS, DEFAULT_MIN_MESSAGE_CHARS, 1),
+			1,
+		),
+		timeoutMs: parseInteger(settings.timeoutMs, parseInteger(env.PI_HEADROOM_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100), 100),
 	};
 }
 
@@ -39,17 +78,24 @@ function normalizeBaseUrl(raw: string): string {
 	return trimmed.replace(/\/+$/, "");
 }
 
-function parseBoolean(raw: string | undefined, fallback: boolean): boolean {
+function parseString(raw: unknown, fallback: string): string {
+	if (typeof raw !== "string") return fallback;
+	return raw.trim() || fallback;
+}
+
+function parseBoolean(raw: unknown, fallback: boolean): boolean {
 	if (raw === undefined) return fallback;
+	if (typeof raw === "boolean") return raw;
+	if (typeof raw !== "string") 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 {
+function parseInteger(raw: unknown, fallback: number, min: number): number {
 	if (raw === undefined) return fallback;
-	const parsed = Number.parseInt(raw, 10);
+	const parsed = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseInt(raw, 10) : Number.NaN;
 	if (!Number.isFinite(parsed) || parsed < min) return fallback;
-	return parsed;
+	return Math.trunc(parsed);
 }

package/index.ts

@@ -250,8 +250,13 @@ function recordAppliedCompression(stats: HeadroomStats, result: CompressResult,
 }
 
 function recordCompressionError(runtime: HeadroomRuntime, ctx: ExtensionContext, error: unknown): void {
+	runtime.state.stats.lastError = getErrorMessage(error);
+	if (isAbortOrTimeoutError(error)) {
+		runtime.refreshStatus(ctx);
+		return;
+	}
+
 	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(
@@ -262,6 +267,23 @@ function recordCompressionError(runtime: HeadroomRuntime, ctx: ExtensionContext,
 	runtime.refreshStatus(ctx);
 }
 
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isAbortOrTimeoutError(error: unknown): boolean {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error as { cause?: unknown; message?: unknown; name?: unknown };
+	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: HeadroomRuntime, command: Subcommand, ctx: ExtensionContext): Promise<void> {
 	if (command === "on") {
 		runtime.state.enabled = true;
@@ -303,19 +325,33 @@ function refreshStatus(ctx: ExtensionContext, config: HeadroomConfig, state: Hea
 	ctx.ui.setStatus(STATUS_KEY, renderFooterStatus(ctx, config, state));
 }
 
+type HeadroomStatusColor = "dim" | "warning" | "success";
+
+type HeadroomStatusTheme = {
+	fg(color: HeadroomStatusColor, text: string): string;
+};
+
+function isHeadroomStatusTheme(theme: unknown): theme is HeadroomStatusTheme {
+	return typeof (theme as { fg?: unknown } | null)?.fg === "function";
+}
+
+function createStatusPainter(theme: unknown): (color: HeadroomStatusColor, text: string) => string {
+	if (isHeadroomStatusTheme(theme)) return (color, text) => theme.fg(color, text);
+	return (_color, text) => text;
+}
+
 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 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 (
-		theme.fg("success", "✓") +
-		theme.fg("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`)
+		paint("success", "✓") + paint("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`)
 	);
 }
 
@@ -414,3 +450,8 @@ function parseSubcommand(args: string): Subcommand {
 	const normalized = args.trim().toLowerCase();
 	return SUBCOMMANDS.includes(normalized as Subcommand) ? (normalized as Subcommand) : "status";
 }
+
+export const __test__ = {
+	isAbortOrTimeoutError,
+	renderFooterStatus,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-headroom",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Headroom token compression for pi — compress large tool results via a local Headroom proxy to reclaim context window.",
   "license": "MIT",
   "repository": {