@lll9p/pi-better-compaction 0.2.0

package/src/config.ts

@@ -0,0 +1,157 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import {
+	DEFAULT_EXTENSION_CONFIG,
+	EXTENSION_ID,
+	RESPONSES_COMPACT_CAPABLE_APIS,
+	THINKING_LEVELS,
+	type ExtensionConfig,
+	type LoadedExtensionConfig,
+} from "./types";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", EXTENSION_ID);
+export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isFile(filePath: string): boolean {
+	try {
+		return fs.statSync(filePath).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function readJsonObject(filePath: string, warnings: string[]): Record<string, unknown> | undefined {
+	if (!isFile(filePath)) return undefined;
+
+	try {
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		if (isRecord(parsed)) return parsed;
+		warnings.push(`Ignoring ${filePath}: expected a JSON object at the top level.`);
+		return undefined;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`Ignoring ${filePath}: ${message}`);
+		return undefined;
+	}
+}
+
+function resolveConfiguredPath(rawPath: string, baseDir: string): string {
+	if (rawPath.startsWith("~/")) {
+		return path.join(os.homedir(), rawPath.slice(2));
+	}
+	if (path.isAbsolute(rawPath)) {
+		return path.resolve(rawPath);
+	}
+	return path.resolve(baseDir, rawPath);
+}
+
+function toBoolean(value: unknown, fieldPath: string, warnings: string[]): boolean | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "boolean") return value;
+	warnings.push(`Ignoring ${fieldPath}: expected a boolean.`);
+	return undefined;
+}
+
+function toModelSpec(value: unknown, fieldPath: string, warnings: string[]): string | null | undefined {
+	if (value === undefined) return undefined;
+	// Explicit null clears a spec, matching the documented "unset = current model" behavior.
+	if (value === null) return null;
+	if (typeof value === "string" && value.trim().length > 0) {
+		return value.trim();
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected "provider/model-id" or null.`);
+	return undefined;
+}
+
+function toThinkingLevel(value: unknown, fieldPath: string, warnings: string[]): ThinkingLevel | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(value)) {
+		return value as ThinkingLevel;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of ${THINKING_LEVELS.join(", ")}.`);
+	return undefined;
+}
+
+function toResponsesCompactApis(value: unknown, fieldPath: string, warnings: string[]): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+		warnings.push(`Ignoring ${fieldPath}: expected a string array.`);
+		return undefined;
+	}
+
+	const capable = new Set<string>(RESPONSES_COMPACT_CAPABLE_APIS);
+	const accepted: string[] = [];
+	for (const item of new Set(value.map((entry) => entry.trim()).filter(Boolean))) {
+		if (capable.has(item)) {
+			accepted.push(item);
+		} else {
+			warnings.push(
+				`Ignoring ${fieldPath} entry "${item}": only ${[...RESPONSES_COMPACT_CAPABLE_APIS].join(", ")} support the compact endpoint.`,
+			);
+		}
+	}
+
+	return accepted;
+}
+
+/**
+ * Load extension config. Single source: `~/.pi/agent/extensions/pi-better-compaction/config.json`
+ * merged over code defaults. A missing file silently yields the defaults.
+ */
+export function loadExtensionConfig(configPath: string = CONFIG_PATH): LoadedExtensionConfig {
+	const warnings: string[] = [];
+	const resolved: ExtensionConfig = {
+		...DEFAULT_EXTENSION_CONFIG,
+		responsesCompactApis: [...DEFAULT_EXTENSION_CONFIG.responsesCompactApis],
+	};
+	let source: string | undefined;
+
+	const raw = readJsonObject(configPath, warnings);
+	if (raw) {
+		source = configPath;
+
+		resolved.enabled = toBoolean(raw.enabled, "enabled", warnings) ?? resolved.enabled;
+		resolved.notifyOnLoad = toBoolean(raw.notifyOnLoad, "notifyOnLoad", warnings) ?? resolved.notifyOnLoad;
+		resolved.debug = toBoolean(raw.debug, "debug", warnings) ?? resolved.debug;
+		resolved.logProviderPayloads =
+			toBoolean(raw.logProviderPayloads, "logProviderPayloads", warnings) ?? resolved.logProviderPayloads;
+		resolved.logCompactResponses =
+			toBoolean(raw.logCompactResponses, "logCompactResponses", warnings) ?? resolved.logCompactResponses;
+		resolved.redactSensitiveData =
+			toBoolean(raw.redactSensitiveData, "redactSensitiveData", warnings) ?? resolved.redactSensitiveData;
+
+		const modelSpec = toModelSpec(raw.compactionModel, "compactionModel", warnings);
+		if (modelSpec !== undefined) {
+			resolved.compactionModel = modelSpec === null ? undefined : modelSpec;
+		}
+
+		resolved.compactionThinkingLevel =
+			toThinkingLevel(raw.compactionThinkingLevel, "compactionThinkingLevel", warnings) ??
+			resolved.compactionThinkingLevel;
+
+		const apis = toResponsesCompactApis(raw.responsesCompactApis, "responsesCompactApis", warnings);
+		if (apis !== undefined) {
+			resolved.responsesCompactApis = apis;
+		}
+
+		if (typeof raw.artifactRoot === "string" && raw.artifactRoot.trim().length > 0) {
+			resolved.artifactRoot = raw.artifactRoot.trim();
+		} else if (raw.artifactRoot !== undefined) {
+			warnings.push("Ignoring artifactRoot: expected a non-empty string.");
+		}
+	}
+
+	resolved.artifactRoot = resolveConfiguredPath(resolved.artifactRoot, path.dirname(configPath));
+
+	return {
+		config: resolved,
+		source,
+		warnings,
+	};
+}

package/src/debug.ts

@@ -0,0 +1,165 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	EXTENSION_ID,
+	REDACTED_VALUE,
+	type ArtifactContext,
+	type ArtifactPaths,
+	type DebugArtifactEnvelope,
+	type DebugArtifactKind,
+	type ExtensionConfig,
+	type RedactOptions,
+} from "./types";
+
+const SENSITIVE_KEY_RE = /(authorization|api[-_]?key|token|secret|password|cookie|set-cookie|signature|credential|oauth|auth)/i;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._\-+/=]+/gi;
+const OPENAI_KEY_RE = /\bsk-[A-Za-z0-9\-_]+\b/g;
+const HEADER_TOKEN_RE = /\b(x-api-key|api-key|authorization)\b\s*[:=]\s*[^\s,;]+/gi;
+
+function ensureDir(dirPath: string) {
+	fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function toSessionInfo(context: ArtifactContext) {
+	const maybeExtensionContext = context as Pick<ExtensionContext, "cwd" | "sessionManager">;
+	const sessionManager = maybeExtensionContext.sessionManager;
+	if (sessionManager) {
+		return {
+			cwd: context.cwd,
+			sessionId: sessionManager.getSessionId(),
+			sessionFile: sessionManager.getSessionFile(),
+			sessionDir: sessionManager.getSessionDir(),
+		};
+	}
+	return context;
+}
+
+function sanitizePathSegment(value: string | undefined, fallback: string): string {
+	if (!value) return fallback;
+	const normalized = value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+	return normalized.length > 0 ? normalized : fallback;
+}
+
+function redactInlineSecrets(value: string, placeholder: string): string {
+	return value
+		.replace(BEARER_RE, `Bearer ${placeholder}`)
+		.replace(OPENAI_KEY_RE, placeholder)
+		.replace(HEADER_TOKEN_RE, (_match, key: string) => `${key}: ${placeholder}`);
+}
+
+function shouldRedactKey(key: string): boolean {
+	return SENSITIVE_KEY_RE.test(key);
+}
+
+export function redactValue(value: unknown, options: RedactOptions = {}): unknown {
+	const placeholder = options.placeholder ?? REDACTED_VALUE;
+	const seen = new WeakSet<object>();
+
+	const visit = (input: unknown): unknown => {
+		if (typeof input === "string") {
+			return redactInlineSecrets(input, placeholder);
+		}
+		if (!input || typeof input !== "object") {
+			return input;
+		}
+		if (seen.has(input)) {
+			return "[Circular]";
+		}
+		seen.add(input);
+
+		if (Array.isArray(input)) {
+			return input.map((item) => visit(item));
+		}
+
+		const result: Record<string, unknown> = {};
+		for (const [key, item] of Object.entries(input)) {
+			result[key] = shouldRedactKey(key) ? placeholder : visit(item);
+		}
+		return result;
+	};
+
+	return visit(value);
+}
+
+export function resolveArtifactPaths(settings: ExtensionConfig, context: ArtifactContext): ArtifactPaths {
+	const sessionInfo = toSessionInfo(context);
+	const rootDir = settings.artifactRoot.startsWith("~/")
+		? path.join(os.homedir(), settings.artifactRoot.slice(2))
+		: path.resolve(settings.artifactRoot);
+	const sessionDir = path.join(rootDir, "sessions", sanitizePathSegment(sessionInfo.sessionId, "no-session"));
+
+	return {
+		rootDir,
+		sessionDir,
+		providerRequestsDir: path.join(sessionDir, "provider-requests"),
+		compactResponsesDir: path.join(sessionDir, "compact-responses"),
+		compactionDir: path.join(sessionDir, "compaction-events"),
+		lifecycleDir: path.join(sessionDir, "lifecycle"),
+	};
+}
+
+function selectArtifactDirectory(paths: ArtifactPaths, kind: DebugArtifactKind): string {
+	switch (kind) {
+		case "provider-request":
+			return paths.providerRequestsDir;
+		case "compact-response":
+			return paths.compactResponsesDir;
+		case "compaction-event":
+			return paths.compactionDir;
+		case "lifecycle":
+		default:
+			return paths.lifecycleDir;
+	}
+}
+
+function shouldWriteArtifact(kind: DebugArtifactKind, settings: ExtensionConfig): boolean {
+	switch (kind) {
+		case "provider-request":
+			return settings.logProviderPayloads;
+		case "compact-response":
+			return settings.logCompactResponses;
+		case "compaction-event":
+		case "lifecycle":
+			return settings.debug;
+		default:
+			return false;
+	}
+}
+
+export function writeDebugArtifact(
+	kind: DebugArtifactKind,
+	data: unknown,
+	settings: ExtensionConfig,
+	context: ArtifactContext,
+): string | undefined {
+	if (!shouldWriteArtifact(kind, settings)) {
+		return undefined;
+	}
+
+	const sessionInfo = toSessionInfo(context);
+	const paths = resolveArtifactPaths(settings, context);
+	const targetDir = selectArtifactDirectory(paths, kind);
+	ensureDir(targetDir);
+
+	const timestamp = new Date().toISOString();
+	const fileName = `${timestamp.replace(/[.:]/g, "-")}-${kind}.json`;
+	const filePath = path.join(targetDir, fileName);
+	const envelope: DebugArtifactEnvelope = {
+		extension: EXTENSION_ID,
+		kind,
+		timestamp,
+		cwd: sessionInfo.cwd,
+		sessionId: sessionInfo.sessionId,
+		sessionFile: sessionInfo.sessionFile,
+		sessionDir: sessionInfo.sessionDir,
+		redaction: {
+			enabled: settings.redactSensitiveData,
+		},
+		data: settings.redactSensitiveData ? redactValue(data) : data,
+	};
+
+	fs.writeFileSync(filePath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+	return filePath;
+}

package/src/details-store.ts

@@ -0,0 +1,151 @@
+import type { CompactionEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+import {
+	isNativeCompactionDetails,
+	isNativeCompactionEntry,
+	type NativeCompactionDetails,
+	type NativeCompactionEntry,
+	type NativeCompactionIdentity,
+} from "./types";
+
+export type NativeCompactionEntryMatch = Partial<NativeCompactionIdentity>;
+
+export type LatestNativeCompactionResolutionFailureReason =
+	| "no-compaction"
+	| "latest-compaction-not-native"
+	| "latest-native-compaction-mismatch";
+
+export type LatestNativeCompactionResolution =
+	| {
+			ok: true;
+			entry: NativeCompactionEntry;
+			index: number;
+			latestCompactionIndex: number;
+	  }
+	| {
+			ok: false;
+			reason: LatestNativeCompactionResolutionFailureReason;
+			latestCompactionIndex?: number;
+			latestCompaction?: CompactionEntry;
+	  };
+
+function entryMatches(entry: NativeCompactionEntry, match: NativeCompactionEntryMatch): boolean {
+	const details = entry.details;
+	if (!details) {
+		return false;
+	}
+
+	return (
+		(match.provider === undefined || details.provider === match.provider) &&
+		(match.api === undefined || details.api === match.api) &&
+		(match.model === undefined || details.model === match.model) &&
+		(match.baseUrl === undefined || details.baseUrl === match.baseUrl)
+	);
+}
+
+export function getNativeCompactionDetails(
+	entry: CompactionEntry | SessionEntry | undefined,
+): NativeCompactionDetails | undefined {
+	if (!entry || entry.type !== "compaction") {
+		return undefined;
+	}
+
+	return isNativeCompactionDetails(entry.details) ? entry.details : undefined;
+}
+
+export function isPersistedNativeCompactionEntry(
+	entry: CompactionEntry | SessionEntry | undefined,
+): entry is NativeCompactionEntry {
+	return isNativeCompactionEntry(entry);
+}
+
+export function findLatestCompactionEntryIndex(entries: readonly SessionEntry[]): number | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		if (entries[index]?.type === "compaction") {
+			return index;
+		}
+	}
+
+	return undefined;
+}
+
+export function findLatestCompactionEntry(entries: readonly SessionEntry[]): CompactionEntry | undefined {
+	const index = findLatestCompactionEntryIndex(entries);
+	return index === undefined ? undefined : (entries[index] as CompactionEntry);
+}
+
+export function findLatestNativeCompactionEntryIndex(
+	entries: readonly SessionEntry[],
+	match: NativeCompactionEntryMatch = {},
+): number | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (!isPersistedNativeCompactionEntry(entry)) {
+			continue;
+		}
+
+		if (!entryMatches(entry, match)) {
+			continue;
+		}
+
+		return index;
+	}
+
+	return undefined;
+}
+
+export function findLatestNativeCompactionEntry(
+	entries: readonly SessionEntry[],
+	match: NativeCompactionEntryMatch = {},
+): NativeCompactionEntry | undefined {
+	const index = findLatestNativeCompactionEntryIndex(entries, match);
+	return index === undefined ? undefined : (entries[index] as NativeCompactionEntry);
+}
+
+export function findLatestNativeCompactionDetails(
+	entries: readonly SessionEntry[],
+	match: NativeCompactionEntryMatch = {},
+): NativeCompactionDetails | undefined {
+	return findLatestNativeCompactionEntry(entries, match)?.details;
+}
+
+export function resolveLatestNativeCompactionEntry(
+	entries: readonly SessionEntry[],
+	match: NativeCompactionEntryMatch = {},
+): LatestNativeCompactionResolution {
+	const latestCompactionIndex = findLatestCompactionEntryIndex(entries);
+	if (latestCompactionIndex === undefined) {
+		return {
+			ok: false,
+			reason: "no-compaction",
+		};
+	}
+
+	const latestCompaction = entries[latestCompactionIndex];
+	if (!latestCompaction || latestCompaction.type !== "compaction" || !isPersistedNativeCompactionEntry(latestCompaction)) {
+		return {
+			ok: false,
+			reason: "latest-compaction-not-native",
+			latestCompactionIndex,
+			latestCompaction:
+				latestCompaction && latestCompaction.type === "compaction"
+					? (latestCompaction as CompactionEntry)
+					: undefined,
+		};
+	}
+
+	if (!entryMatches(latestCompaction, match)) {
+		return {
+			ok: false,
+			reason: "latest-native-compaction-mismatch",
+			latestCompactionIndex,
+			latestCompaction,
+		};
+	}
+
+	return {
+		ok: true,
+		entry: latestCompaction,
+		index: latestCompactionIndex,
+		latestCompactionIndex,
+	};
+}