@raquezha/noheadroom 0.0.2

package/extensions/bridge.ts

@@ -0,0 +1,241 @@
+import type { ImageContent, TextContent, ToolCall } from "@earendil-works/pi-ai";
+import type {
+	AgentMessage,
+	ApplyCompressionOptions,
+	ApplyCompressionResult,
+	CompressionMapping,
+	CompressionPayload,
+	OpenAIAssistantMessage,
+	OpenAIMessage,
+	OpenAIToolCall,
+} from "./types.js";
+
+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: {
+			// Headroom may protect/exclude built-in agent tool names such as `read` and `bash`.
+			// This payload is only for compression alignment; Pi's original tool metadata is preserved
+			// in originalMessages and restored when applying the compressed toolResult text.
+			name: "pi_tool_result",
+			arguments: JSON.stringify({ originalToolName: toolCall.name }),
+		},
+	};
+}
+
+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/extensions/client.ts

@@ -0,0 +1,112 @@
+import type { CompressResult, OpenAIMessage } from "./types.js";
+
+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/extensions/config.ts

@@ -0,0 +1,101 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { HeadroomConfig } from "./types.js";
+
+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 = 30_000;
+
+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(settings.enabled, parseBoolean(env.PI_HEADROOM_ENABLED, true)),
+		baseUrl,
+		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),
+	};
+}
+
+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 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: unknown, fallback: number, min: number): number {
+	if (raw === undefined) return fallback;
+	const parsed = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseInt(raw, 10) : Number.NaN;
+	if (!Number.isFinite(parsed) || parsed < min) return fallback;
+	return Math.trunc(parsed);
+}