pi-readcache 0.1.0

package/src/path.ts

@@ -0,0 +1,246 @@
+import { accessSync, constants } from "node:fs";
+import * as os from "node:os";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { SCOPE_FULL, scopeRange } from "./constants.js";
+import type { ScopeKey } from "./types.js";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+
+function normalizeUnicodeSpaces(value: string): string {
+	return value.replace(UNICODE_SPACES, " ");
+}
+
+function normalizeAtPrefix(value: string): string {
+	return value.startsWith("@") ? value.slice(1) : value;
+}
+
+function tryMacOSScreenshotPath(filePath: string): string {
+	return filePath.replace(/ (AM|PM)\./g, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+
+function tryNfdVariant(filePath: string): string {
+	return filePath.normalize("NFD");
+}
+
+function tryCurlyQuoteVariant(filePath: string): string {
+	return filePath.replace(/'/g, "\u2019");
+}
+
+function fileExists(filePath: string): boolean {
+	try {
+		accessSync(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function validateLineNumber(value: number, label: "start" | "end"): void {
+	if (!Number.isInteger(value) || value <= 0) {
+		throw new Error(`Invalid ${label} line number "${value}". Line numbers must be positive integers.`);
+	}
+}
+
+function parseRangeSuffix(suffix: string): { start: number; end?: number } {
+	const singleLineMatch = /^(\d+)$/.exec(suffix);
+	if (singleLineMatch) {
+		const startRaw = singleLineMatch[1];
+		if (!startRaw) {
+			throw new Error(`Invalid range suffix "${suffix}". Use :<start> or :<start>-<end>.`);
+		}
+		const start = Number.parseInt(startRaw, 10);
+		validateLineNumber(start, "start");
+		return { start };
+	}
+
+	const rangeMatch = /^(\d+)-(\d+)$/.exec(suffix);
+	if (rangeMatch) {
+		const startRaw = rangeMatch[1];
+		const endRaw = rangeMatch[2];
+		if (!startRaw || !endRaw) {
+			throw new Error(`Invalid range suffix "${suffix}". Use :<start> or :<start>-<end>.`);
+		}
+		const start = Number.parseInt(startRaw, 10);
+		const end = Number.parseInt(endRaw, 10);
+		validateLineNumber(start, "start");
+		validateLineNumber(end, "end");
+		if (end < start) {
+			throw new Error(`Invalid range "${suffix}": end line must be greater than or equal to start line.`);
+		}
+		return { start, end };
+	}
+
+	throw new Error(`Invalid range suffix "${suffix}". Use :<start> or :<start>-<end>.`);
+}
+
+export interface ParsedReadPath {
+	pathInput: string;
+	absolutePath: string;
+	offset?: number;
+	limit?: number;
+	parsedFromPath: boolean;
+}
+
+export interface NormalizedRange {
+	start: number;
+	end: number;
+	totalLines: number;
+}
+
+export function expandPath(filePath: string): string {
+	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+	if (normalized === "~") {
+		return os.homedir();
+	}
+	if (normalized.startsWith("~/")) {
+		return os.homedir() + normalized.slice(1);
+	}
+	return normalized;
+}
+
+export function resolveToCwd(filePath: string, cwd: string): string {
+	const expanded = expandPath(filePath);
+	if (isAbsolute(expanded)) {
+		return expanded;
+	}
+	return resolvePath(cwd, expanded);
+}
+
+export function resolveReadPath(filePath: string, cwd: string): string {
+	const resolved = resolveToCwd(filePath, cwd);
+	if (fileExists(resolved)) {
+		return resolved;
+	}
+
+	const amPmVariant = tryMacOSScreenshotPath(resolved);
+	if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+		return amPmVariant;
+	}
+
+	const nfdVariant = tryNfdVariant(resolved);
+	if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+		return nfdVariant;
+	}
+
+	const curlyVariant = tryCurlyQuoteVariant(resolved);
+	if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+		return curlyVariant;
+	}
+
+	const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+	if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+		return nfdCurlyVariant;
+	}
+
+	return resolved;
+}
+
+export function normalizeInputPath(rawPath: string, cwd: string): ParsedReadPath {
+	return {
+		pathInput: rawPath,
+		absolutePath: resolveReadPath(rawPath, cwd),
+		parsedFromPath: false,
+	};
+}
+
+export function parseTrailingRangeIfNeeded(
+	rawPath: string,
+	explicitOffset: number | undefined,
+	explicitLimit: number | undefined,
+	cwd: string,
+): ParsedReadPath {
+	if (explicitOffset !== undefined || explicitLimit !== undefined) {
+		const parsed: ParsedReadPath = {
+			pathInput: rawPath,
+			absolutePath: resolveReadPath(rawPath, cwd),
+			parsedFromPath: false,
+		};
+		if (explicitOffset !== undefined) {
+			parsed.offset = explicitOffset;
+		}
+		if (explicitLimit !== undefined) {
+			parsed.limit = explicitLimit;
+		}
+		return parsed;
+	}
+
+	const resolvedRawPath = resolveReadPath(rawPath, cwd);
+	if (fileExists(resolvedRawPath)) {
+		return {
+			pathInput: rawPath,
+			absolutePath: resolvedRawPath,
+			parsedFromPath: false,
+		};
+	}
+
+	const lastColonIndex = rawPath.lastIndexOf(":");
+	if (lastColonIndex <= 0 || lastColonIndex === rawPath.length - 1) {
+		return {
+			pathInput: rawPath,
+			absolutePath: resolvedRawPath,
+			parsedFromPath: false,
+		};
+	}
+
+	const candidatePath = rawPath.slice(0, lastColonIndex);
+	const suffix = rawPath.slice(lastColonIndex + 1);
+	const resolvedCandidatePath = resolveReadPath(candidatePath, cwd);
+	if (!fileExists(resolvedCandidatePath)) {
+		return {
+			pathInput: rawPath,
+			absolutePath: resolvedRawPath,
+			parsedFromPath: false,
+		};
+	}
+
+	const parsedRange = parseRangeSuffix(suffix);
+	const offset = parsedRange.start;
+	const limit = parsedRange.end !== undefined ? parsedRange.end - parsedRange.start + 1 : undefined;
+
+	const parsed: ParsedReadPath = {
+		pathInput: candidatePath,
+		absolutePath: resolvedCandidatePath,
+		offset,
+		parsedFromPath: true,
+	};
+	if (limit !== undefined) {
+		parsed.limit = limit;
+	}
+	return parsed;
+}
+
+export function normalizeOffsetLimit(
+	offset: number | undefined,
+	limit: number | undefined,
+	totalLines: number,
+): NormalizedRange {
+	if (offset !== undefined && (!Number.isInteger(offset) || offset <= 0)) {
+		throw new Error(`Invalid offset "${offset}". Offset must be a positive integer.`);
+	}
+	if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+		throw new Error(`Invalid limit "${limit}". Limit must be a positive integer.`);
+	}
+
+	const normalizedTotalLines = Math.max(1, totalLines);
+	const start = offset ?? 1;
+	if (start > normalizedTotalLines) {
+		throw new Error(`Offset ${start} is beyond end of file (${normalizedTotalLines} lines total)`);
+	}
+
+	const unclampedEnd = limit !== undefined ? start + limit - 1 : normalizedTotalLines;
+	const end = Math.min(unclampedEnd, normalizedTotalLines);
+
+	return {
+		start,
+		end,
+		totalLines: normalizedTotalLines,
+	};
+}
+
+export function scopeKeyForRange(start: number, end: number, totalLines: number): ScopeKey {
+	if (start === 1 && end === totalLines) {
+		return SCOPE_FULL;
+	}
+	return scopeRange(start, end);
+}

package/src/replay.ts

@@ -0,0 +1,257 @@
+import type { ExtensionContext, SessionEntry } from "@mariozechner/pi-coding-agent";
+import { SCOPE_FULL } from "./constants.js";
+import { extractInvalidationFromSessionEntry, extractReadMetaFromSessionEntry } from "./meta.js";
+import type {
+	KnowledgeMap,
+	ReadCacheInvalidationV1,
+	ReadCacheMetaV1,
+	ScopeKey,
+	ScopeTrust,
+} from "./types.js";
+
+type SessionManagerView = ExtensionContext["sessionManager"];
+
+const OVERLAY_SEQ_START = 1_000_000_000;
+
+interface OverlayState {
+	leafId: string | null;
+	knowledge: KnowledgeMap;
+}
+
+export interface ReplayRuntimeState {
+	memoByLeaf: Map<string, KnowledgeMap>;
+	overlayBySession: Map<string, OverlayState>;
+	nextOverlaySeq: number;
+}
+
+export interface ReplayBoundary {
+	startIndex: number;
+	boundaryKey: string;
+}
+
+function cloneKnowledgeMap(source: KnowledgeMap): KnowledgeMap {
+	const cloned: KnowledgeMap = new Map();
+	for (const [pathKey, scopes] of source.entries()) {
+		const clonedScopes = new Map<ScopeKey, ScopeTrust>();
+		for (const [scopeKey, trust] of scopes.entries()) {
+			clonedScopes.set(scopeKey, { ...trust });
+		}
+		cloned.set(pathKey, clonedScopes);
+	}
+	return cloned;
+}
+
+function getMemoKey(sessionId: string, leafId: string | null, boundaryKey: string): string {
+	return `${sessionId}:${leafId ?? "null"}:${boundaryKey}`;
+}
+
+function ensureScopeMap(knowledge: KnowledgeMap, pathKey: string): Map<ScopeKey, ScopeTrust> {
+	const existing = knowledge.get(pathKey);
+	if (existing) {
+		return existing;
+	}
+	const created = new Map<ScopeKey, ScopeTrust>();
+	knowledge.set(pathKey, created);
+	return created;
+}
+
+export function getTrust(knowledge: KnowledgeMap, pathKey: string, scopeKey: ScopeKey): ScopeTrust | undefined {
+	return knowledge.get(pathKey)?.get(scopeKey);
+}
+
+export function setTrust(knowledge: KnowledgeMap, pathKey: string, scopeKey: ScopeKey, hash: string, seq: number): void {
+	const scopes = ensureScopeMap(knowledge, pathKey);
+	scopes.set(scopeKey, { hash, seq });
+}
+
+function mergeKnowledge(base: KnowledgeMap, overlay: KnowledgeMap): KnowledgeMap {
+	const merged = cloneKnowledgeMap(base);
+	for (const [pathKey, overlayScopes] of overlay.entries()) {
+		const targetScopes = ensureScopeMap(merged, pathKey);
+		for (const [scopeKey, trust] of overlayScopes.entries()) {
+			targetScopes.set(scopeKey, { ...trust });
+		}
+	}
+	return merged;
+}
+
+function ensureOverlayForLeaf(runtimeState: ReplayRuntimeState, sessionId: string, leafId: string | null): OverlayState {
+	const existing = runtimeState.overlayBySession.get(sessionId);
+	if (!existing || existing.leafId !== leafId) {
+		const fresh: OverlayState = {
+			leafId,
+			knowledge: new Map(),
+		};
+		runtimeState.overlayBySession.set(sessionId, fresh);
+		return fresh;
+	}
+	return existing;
+}
+
+function leafHasChildren(sessionManager: SessionManagerView, leafId: string | null): boolean {
+	if (!leafId) {
+		return false;
+	}
+	return sessionManager.getEntries().some((entry) => entry.parentId === leafId);
+}
+
+export function createReplayRuntimeState(): ReplayRuntimeState {
+	return {
+		memoByLeaf: new Map(),
+		overlayBySession: new Map(),
+		nextOverlaySeq: OVERLAY_SEQ_START,
+	};
+}
+
+export function clearReplayRuntimeState(runtimeState: ReplayRuntimeState): void {
+	runtimeState.memoByLeaf.clear();
+	runtimeState.overlayBySession.clear();
+	runtimeState.nextOverlaySeq = OVERLAY_SEQ_START;
+}
+
+export function findReplayStartIndex(branchEntries: SessionEntry[]): ReplayBoundary {
+	for (let index = branchEntries.length - 1; index >= 0; index -= 1) {
+		const entry = branchEntries[index];
+		if (!entry || entry.type !== "compaction") {
+			continue;
+		}
+
+		return {
+			startIndex: Math.min(index + 1, branchEntries.length),
+			boundaryKey: `compaction:${entry.id}`,
+		};
+	}
+
+	return {
+		startIndex: 0,
+		boundaryKey: "root",
+	};
+}
+
+export function applyReadMetaTransition(knowledge: KnowledgeMap, meta: ReadCacheMetaV1, seq: number): void {
+	const { pathKey, scopeKey, servedHash, baseHash, mode } = meta;
+	const fullTrust = getTrust(knowledge, pathKey, SCOPE_FULL);
+	const rangeTrust = scopeKey === SCOPE_FULL ? undefined : getTrust(knowledge, pathKey, scopeKey);
+
+	if (mode === "full" || mode === "full_fallback") {
+		setTrust(knowledge, pathKey, scopeKey, servedHash, seq);
+		return;
+	}
+
+	if (mode === "unchanged" && scopeKey === SCOPE_FULL) {
+		if (!baseHash) {
+			return;
+		}
+		if (!fullTrust || fullTrust.hash !== baseHash) {
+			return;
+		}
+		if (servedHash !== baseHash) {
+			return;
+		}
+		setTrust(knowledge, pathKey, SCOPE_FULL, servedHash, seq);
+		return;
+	}
+
+	if (mode === "diff" && scopeKey === SCOPE_FULL) {
+		if (!baseHash) {
+			return;
+		}
+		if (!fullTrust || fullTrust.hash !== baseHash) {
+			return;
+		}
+		setTrust(knowledge, pathKey, SCOPE_FULL, servedHash, seq);
+		return;
+	}
+
+	if (mode === "unchanged_range" && scopeKey !== SCOPE_FULL) {
+		if (!baseHash) {
+			return;
+		}
+		if (rangeTrust?.hash !== baseHash && fullTrust?.hash !== baseHash) {
+			return;
+		}
+		setTrust(knowledge, pathKey, scopeKey, servedHash, seq);
+	}
+}
+
+export function applyInvalidation(knowledge: KnowledgeMap, invalidation: ReadCacheInvalidationV1): void {
+	const scopes = knowledge.get(invalidation.pathKey);
+	if (!scopes) {
+		return;
+	}
+
+	if (invalidation.scopeKey === SCOPE_FULL) {
+		knowledge.delete(invalidation.pathKey);
+		return;
+	}
+
+	scopes.delete(invalidation.scopeKey);
+	if (scopes.size === 0) {
+		knowledge.delete(invalidation.pathKey);
+	}
+}
+
+export function replayKnowledgeFromBranch(branchEntries: SessionEntry[], startIndex: number): KnowledgeMap {
+	const knowledge: KnowledgeMap = new Map();
+	const normalizedStart = Math.max(0, Math.min(startIndex, branchEntries.length));
+	let seq = 0;
+
+	for (let index = normalizedStart; index < branchEntries.length; index += 1) {
+		const entry = branchEntries[index];
+		if (!entry) {
+			continue;
+		}
+
+		const meta = extractReadMetaFromSessionEntry(entry);
+		if (meta) {
+			seq += 1;
+			applyReadMetaTransition(knowledge, meta, seq);
+			continue;
+		}
+
+		const invalidation = extractInvalidationFromSessionEntry(entry);
+		if (invalidation) {
+			applyInvalidation(knowledge, invalidation);
+		}
+	}
+
+	return knowledge;
+}
+
+export function buildKnowledgeForLeaf(
+	sessionManager: SessionManagerView,
+	runtimeState: ReplayRuntimeState,
+): KnowledgeMap {
+	const sessionId = sessionManager.getSessionId();
+	const leafId = sessionManager.getLeafId();
+	const branchEntries = sessionManager.getBranch();
+	const boundary = findReplayStartIndex(branchEntries);
+	const memoKey = getMemoKey(sessionId, leafId, boundary.boundaryKey);
+
+	let replayKnowledge = runtimeState.memoByLeaf.get(memoKey);
+	if (!replayKnowledge) {
+		replayKnowledge = replayKnowledgeFromBranch(branchEntries, boundary.startIndex);
+		runtimeState.memoByLeaf.set(memoKey, cloneKnowledgeMap(replayKnowledge));
+	}
+
+	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
+	if (leafHasChildren(sessionManager, leafId)) {
+		overlayState.knowledge.clear();
+	}
+	return mergeKnowledge(replayKnowledge, overlayState.knowledge);
+}
+
+export function overlaySet(
+	runtimeState: ReplayRuntimeState,
+	sessionManager: SessionManagerView,
+	pathKey: string,
+	scopeKey: ScopeKey,
+	servedHash: string,
+): void {
+	const sessionId = sessionManager.getSessionId();
+	const leafId = sessionManager.getLeafId();
+	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
+	const seq = runtimeState.nextOverlaySeq;
+	runtimeState.nextOverlaySeq += 1;
+	setTrust(overlayState.knowledge, pathKey, scopeKey, servedHash, seq);
+}

package/src/telemetry.ts

@@ -0,0 +1,108 @@
+import type { ExtensionContext, SessionEntry } from "@mariozechner/pi-coding-agent";
+import { extractReadMetaFromSessionEntry } from "./meta.js";
+import { findReplayStartIndex } from "./replay.js";
+import type { KnowledgeMap, ReadCacheMode } from "./types.js";
+
+export type ReadCacheModeCounts = Record<ReadCacheMode, number>;
+
+export interface ReplayTelemetrySummary {
+	replayStartIndex: number;
+	replayEntryCount: number;
+	modeCounts: ReadCacheModeCounts;
+	estimatedBytesSaved: number;
+	estimatedTokensSaved: number;
+}
+
+function createModeCounts(): ReadCacheModeCounts {
+	return {
+		full: 0,
+		unchanged: 0,
+		unchanged_range: 0,
+		diff: 0,
+		full_fallback: 0,
+	};
+}
+
+function estimateSelectedBytes(meta: {
+	bytes: number;
+	rangeStart: number;
+	rangeEnd: number;
+	totalLines: number;
+}): number {
+	const rangeLines = Math.max(1, meta.rangeEnd - meta.rangeStart + 1);
+	const totalLines = Math.max(1, meta.totalLines);
+	const ratio = Math.min(1, rangeLines / totalLines);
+	return Math.max(1, Math.round(meta.bytes * ratio));
+}
+
+function extractTextBytes(entry: SessionEntry): number {
+	if (entry.type !== "message" || entry.message.role !== "toolResult") {
+		return 0;
+	}
+
+	let total = 0;
+	for (const block of entry.message.content) {
+		if (block.type !== "text") {
+			continue;
+		}
+		total += Buffer.byteLength(block.text, "utf-8");
+	}
+	return total;
+}
+
+function estimateSavedBytes(entry: SessionEntry, baselineBytes: number): number {
+	const servedBytes = extractTextBytes(entry);
+	if (servedBytes <= 0) {
+		return 0;
+	}
+	return Math.max(0, baselineBytes - servedBytes);
+}
+
+function estimateTokensFromBytes(bytes: number): number {
+	if (bytes <= 0) {
+		return 0;
+	}
+	return Math.ceil(bytes / 4);
+}
+
+export function collectReplayTelemetry(sessionManager: ExtensionContext["sessionManager"]): ReplayTelemetrySummary {
+	const branchEntries = sessionManager.getBranch();
+	const boundary = findReplayStartIndex(branchEntries);
+	const modeCounts = createModeCounts();
+	let estimatedBytesSaved = 0;
+
+	for (let index = boundary.startIndex; index < branchEntries.length; index += 1) {
+		const entry = branchEntries[index];
+		if (!entry) {
+			continue;
+		}
+
+		const meta = extractReadMetaFromSessionEntry(entry);
+		if (!meta) {
+			continue;
+		}
+
+		modeCounts[meta.mode] += 1;
+		const baselineBytes = estimateSelectedBytes(meta);
+		estimatedBytesSaved += estimateSavedBytes(entry, baselineBytes);
+	}
+
+	return {
+		replayStartIndex: boundary.startIndex,
+		replayEntryCount: Math.max(0, branchEntries.length - boundary.startIndex),
+		modeCounts,
+		estimatedBytesSaved,
+		estimatedTokensSaved: estimateTokensFromBytes(estimatedBytesSaved),
+	};
+}
+
+export function summarizeKnowledge(knowledge: KnowledgeMap): { trackedFiles: number; trackedScopes: number } {
+	let trackedScopes = 0;
+	for (const scopes of knowledge.values()) {
+		trackedScopes += scopes.size;
+	}
+	return {
+		trackedFiles: knowledge.size,
+		trackedScopes,
+	};
+}

package/src/text.ts

@@ -0,0 +1,43 @@
+import { truncateHead, type TruncationOptions, type TruncationResult } from "@mariozechner/pi-coding-agent";
+
+function validateRange(start: number, end: number): void {
+	if (!Number.isInteger(start) || start <= 0) {
+		throw new Error(`Invalid start line "${start}". Line numbers must be positive integers.`);
+	}
+	if (!Number.isInteger(end) || end <= 0) {
+		throw new Error(`Invalid end line "${end}". Line numbers must be positive integers.`);
+	}
+	if (end < start) {
+		throw new Error(`Invalid range ${start}-${end}. End line must be greater than or equal to start line.`);
+	}
+}
+
+export function splitLines(text: string): string[] {
+	return text.split("\n");
+}
+
+export function sliceByLineRange(text: string, start: number, end: number): string {
+	validateRange(start, end);
+	const lines = splitLines(text);
+	if (start > lines.length) {
+		return "";
+	}
+
+	const clampedEnd = Math.min(end, lines.length);
+	return lines.slice(start - 1, clampedEnd).join("\n");
+}
+
+export function compareSlices(oldText: string, newText: string, start: number, end: number): boolean {
+	return sliceByLineRange(oldText, start, end) === sliceByLineRange(newText, start, end);
+}
+
+export function estimateTokens(text: string): number {
+	if (text.length === 0) {
+		return 0;
+	}
+	return Math.ceil(Buffer.byteLength(text, "utf-8") / 4);
+}
+
+export function truncateForReadcache(content: string, options?: TruncationOptions): TruncationResult {
+	return truncateHead(content, options);
+}