pi-readcache 0.1.1 → 0.2.0

package/README.md

@@ -23,7 +23,7 @@ When the extension is active, `read` may return:
 - unchanged marker (`mode: unchanged`)
 - unchanged range marker (`mode: unchanged_range`)
 - unified diff for full-file reads (`mode: diff`)
-- baseline fallback (`mode: full_fallback`)
+- baseline fallback (`mode: baseline_fallback`)
 
 Plus:
 - `/readcache-status` to inspect replay/coverage/savings
@@ -50,9 +50,9 @@ After installation, you can use pi normally. If pi is already running when you i
 
 | Action | Command | Expected result |
 |---|---|---|
-| Baseline read | `read src/foo.ts` | `mode: full` or `mode: full_fallback` |
+| Baseline read | `read src/foo.ts` | `mode: full` or `mode: baseline_fallback` |
 | Repeat read (no file change) | `read src/foo.ts` | `[readcache: unchanged, ...]` |
-| Range read | `read src/foo.ts:1-120` | `mode: full`, `full_fallback`, or `unchanged_range` |
+| Range read | `read src/foo.ts:1-120` | `mode: full`, `baseline_fallback`, or `unchanged_range` |
 | Inspect replay/cache state | `/readcache-status` | tracked scopes, replay window, mode counts, estimated savings |
 | Invalidate full scope | `/readcache-refresh src/foo.ts` | next full read re-anchors |
 | Invalidate range scope | `/readcache-refresh src/foo.ts 1-120` | next range read re-anchors |
@@ -63,9 +63,24 @@ After installation, you can use pi normally. If pi is already running when you i
 - Compaction is a strict replay barrier for trust reconstruction:
   - replay starts at the latest active `compaction + 1`.
   - pre-compaction trust is not used after that barrier.
-- First read after that barrier for a path/scope will re-anchor with baseline (`full`/`full_fallback`).
+- First read after that barrier for a path/scope will re-anchor with baseline (`full`/`baseline_fallback`).
 - For exact current file text, the assistant should still perform an actual `read` in current context.
 
+### Diff usefulness gate (why you sometimes get full content instead of a diff)
+
+For full-file reads, `mode: diff` is emitted only when the generated patch is clearly more useful than baseline text.
+
+Current defaults:
+- `MAX_DIFF_TO_BASE_RATIO = 0.9`
+  - if `diffBytes >= selectedBytes * 0.9`, diff is considered not useful and falls back to baseline (`mode: baseline_fallback`)
+- `MAX_DIFF_TO_BASE_LINE_RATIO = 0.85`
+  - if patch line count is greater than `selectedRequestedLines * 0.85`, diff is considered too large/noisy and falls back to baseline
+
+Why these defaults:
+- avoids near-full-file patch spam on high-churn edits
+- improves readability for the model versus very large hunks
+- keeps token savings meaningful when diff mode is used
+
 ---
 
 ## For extension developers (and curious cats)
@@ -89,7 +104,7 @@ flowchart TD
   F -- no --> G[mode=full, attach metadata]
   F -- yes + same hash --> H[mode=unchanged/unchanged_range]
   F -- yes + full scope + useful diff --> I[mode=diff]
-  F -- otherwise --> J[mode=full_fallback]
+  F -- otherwise --> J[mode=baseline_fallback]
   G --> K[persist object + overlay trust]
   H --> K
   I --> K

package/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { registerReadcacheCommands } from "./src/commands.js";
 import { clearReplayRuntimeState, createReplayRuntimeState } from "./src/replay.js";
 import { pruneObjectsOlderThan } from "./src/object-store.js";
@@ -6,7 +6,7 @@ import { createReadOverrideTool } from "./src/tool.js";
 
 export default function (pi: ExtensionAPI): void {
 	const runtimeState = createReplayRuntimeState();
-	pi.registerTool(createReadOverrideTool(runtimeState));
+	pi.registerTool(createReadOverrideTool(runtimeState) as unknown as ToolDefinition);
 	registerReadcacheCommands(pi, runtimeState);
 
 	const clearCaches = (): void => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readcache",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "🧠 Pi extension that optimizes read tool calls with replay-aware caching and compaction-safe trust reconstruction",
   "author": "Gurpartap Singh",
   "license": "MIT",

package/src/commands.ts

@@ -5,6 +5,7 @@ import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
+	ToolDefinition,
 } from "@mariozechner/pi-coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import { READCACHE_CUSTOM_TYPE, SCOPE_FULL, scopeRange } from "./constants.js";
@@ -50,7 +51,7 @@ function formatModeCounts(modeCounts: ReturnType<typeof collectReplayTelemetry>[
 		`unchanged=${modeCounts.unchanged}`,
 		`unchanged_range=${modeCounts.unchanged_range}`,
 		`diff=${modeCounts.diff}`,
-		`full_fallback=${modeCounts.full_fallback}`,
+		`baseline_fallback=${modeCounts.baseline_fallback}`,
 	].join(", ");
 }
 
@@ -324,5 +325,5 @@ export function registerReadcacheCommands(pi: ExtensionAPI, runtimeState: Replay
 		},
 	});
 
-	pi.registerTool(createReadcacheRefreshTool(pi, runtimeState));
+	pi.registerTool(createReadcacheRefreshTool(pi, runtimeState) as unknown as ToolDefinition);
 }

package/src/constants.ts

@@ -5,7 +5,8 @@ export const SCOPE_FULL = "full" as const;
 
 export const MAX_DIFF_FILE_BYTES = 2 * 1024 * 1024;
 export const MAX_DIFF_FILE_LINES = 12_000;
-export const MAX_DIFF_TO_BASE_RATIO = 1.0;
+export const MAX_DIFF_TO_BASE_RATIO = 0.9;
+export const MAX_DIFF_TO_BASE_LINE_RATIO = 0.85;
 
 export const DEFAULT_EXCLUDED_PATH_PATTERNS = [
 	".env*",

package/src/diff.ts

@@ -2,6 +2,7 @@ import { formatPatch, structuredPatch } from "diff";
 import {
 	MAX_DIFF_FILE_BYTES,
 	MAX_DIFF_FILE_LINES,
+	MAX_DIFF_TO_BASE_LINE_RATIO,
 	MAX_DIFF_TO_BASE_RATIO,
 } from "./constants.js";
 
@@ -11,6 +12,7 @@ export interface DiffLimits {
 	maxFileBytes: number;
 	maxFileLines: number;
 	maxDiffToBaseRatio: number;
+	maxDiffToBaseLineRatio: number;
 }
 
 export interface DiffComputation {
@@ -25,6 +27,7 @@ export const DEFAULT_DIFF_LIMITS: DiffLimits = {
 	maxFileBytes: MAX_DIFF_FILE_BYTES,
 	maxFileLines: MAX_DIFF_FILE_LINES,
 	maxDiffToBaseRatio: MAX_DIFF_TO_BASE_RATIO,
+	maxDiffToBaseLineRatio: MAX_DIFF_TO_BASE_LINE_RATIO,
 };
 
 function sanitizePathForPatch(pathDisplay: string): string {
@@ -125,6 +128,15 @@ export function isDiffUseful(
 	if (diffBytes === 0) {
 		return false;
 	}
+	if (diffBytes >= selectedBytes * limits.maxDiffToBaseRatio) {
+		return false;
+	}
+
+	const selectedRequestedLines = lineCount(selectedCurrentText);
+	const diffLines = lineCount(diffText);
+	if (diffLines > selectedRequestedLines * limits.maxDiffToBaseLineRatio) {
+		return false;
+	}
 
-	return diffBytes < selectedBytes * limits.maxDiffToBaseRatio;
+	return true;
 }

package/src/meta.ts

@@ -22,14 +22,23 @@ function isNonNegativeInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
 
-function isReadCacheMode(value: unknown): value is ReadCacheMode {
-	return (
-		value === "full" ||
-		value === "unchanged" ||
-		value === "unchanged_range" ||
-		value === "diff" ||
-		value === "full_fallback"
-	);
+function normalizeReadCacheMode(value: unknown): ReadCacheMode | undefined {
+	if (value === "full") {
+		return "full";
+	}
+	if (value === "unchanged") {
+		return "unchanged";
+	}
+	if (value === "unchanged_range") {
+		return "unchanged_range";
+	}
+	if (value === "diff") {
+		return "diff";
+	}
+	if (value === "baseline_fallback") {
+		return "baseline_fallback";
+	}
+	return undefined;
 }
 
 function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reason"] {
@@ -44,7 +53,8 @@ function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reas
 		value === "diff_unavailable_or_empty" ||
 		value === "diff_not_useful" ||
 		value === "diff_payload_truncated" ||
-		value === "diff_emitted"
+		value === "diff_emitted" ||
+		value === "bypass_cache"
 	);
 }
 
@@ -111,48 +121,69 @@ export function isScopeKey(value: unknown): value is ScopeKey {
 	return Number.isInteger(start) && Number.isInteger(end) && start > 0 && end >= start;
 }
 
-export function isReadCacheMetaV1(value: unknown): value is ReadCacheMetaV1 {
+function parseReadCacheMetaV1(value: unknown): ReadCacheMetaV1 | undefined {
 	if (!isRecord(value)) {
-		return false;
+		return undefined;
 	}
 
 	if (value.v !== READCACHE_META_VERSION) {
-		return false;
+		return undefined;
 	}
 
 	if (typeof value.pathKey !== "string" || value.pathKey.length === 0) {
-		return false;
+		return undefined;
 	}
 
 	if (!isScopeKey(value.scopeKey)) {
-		return false;
+		return undefined;
 	}
 
 	if (typeof value.servedHash !== "string" || value.servedHash.length === 0) {
-		return false;
+		return undefined;
 	}
 
-	if (!isReadCacheMode(value.mode)) {
-		return false;
+	const mode = normalizeReadCacheMode(value.mode);
+	if (!mode) {
+		return undefined;
 	}
 
-	const requiresBaseHash = value.mode === "unchanged" || value.mode === "unchanged_range" || value.mode === "diff";
+	const requiresBaseHash = mode === "unchanged" || mode === "unchanged_range" || mode === "diff";
 	if (requiresBaseHash) {
 		if (typeof value.baseHash !== "string" || value.baseHash.length === 0) {
-			return false;
+			return undefined;
 		}
 	} else if (value.baseHash !== undefined && (typeof value.baseHash !== "string" || value.baseHash.length === 0)) {
-		return false;
+		return undefined;
 	}
 
-	return (
-		isPositiveInteger(value.totalLines) &&
-		isPositiveInteger(value.rangeStart) &&
-		isPositiveInteger(value.rangeEnd) &&
-		value.rangeEnd >= value.rangeStart &&
-		isNonNegativeInteger(value.bytes) &&
-		(value.debug === undefined || isReadCacheDebugV1(value.debug))
-	);
+	if (
+		!isPositiveInteger(value.totalLines) ||
+		!isPositiveInteger(value.rangeStart) ||
+		!isPositiveInteger(value.rangeEnd) ||
+		value.rangeEnd < value.rangeStart ||
+		!isNonNegativeInteger(value.bytes) ||
+		(value.debug !== undefined && !isReadCacheDebugV1(value.debug))
+	) {
+		return undefined;
+	}
+
+	return {
+		v: READCACHE_META_VERSION,
+		pathKey: value.pathKey,
+		scopeKey: value.scopeKey,
+		servedHash: value.servedHash,
+		...(typeof value.baseHash === "string" ? { baseHash: value.baseHash } : {}),
+		mode,
+		totalLines: value.totalLines,
+		rangeStart: value.rangeStart,
+		rangeEnd: value.rangeEnd,
+		bytes: value.bytes,
+		...(value.debug !== undefined ? { debug: value.debug } : {}),
+	};
+}
+
+export function isReadCacheMetaV1(value: unknown): value is ReadCacheMetaV1 {
+	return parseReadCacheMetaV1(value) !== undefined;
 }
 
 export function isReadCacheInvalidationV1(value: unknown): value is ReadCacheInvalidationV1 {
@@ -202,11 +233,7 @@ export function extractReadMetaFromSessionEntry(entry: SessionEntry): ReadCacheM
 	}
 
 	const candidate = message.details.readcache;
-	if (!isReadCacheMetaV1(candidate)) {
-		return undefined;
-	}
-
-	return candidate;
+	return parseReadCacheMetaV1(candidate);
 }
 
 export function extractInvalidationFromSessionEntry(entry: SessionEntry): ReadCacheInvalidationV1 | undefined {

package/src/replay.ts

@@ -246,7 +246,7 @@ export function applyReadMetaTransition(
 	const fullTrust = getTrust(knowledge, pathKey, SCOPE_FULL);
 	const rangeTrust = scopeKey === SCOPE_FULL ? undefined : getTrust(knowledge, pathKey, scopeKey);
 
-	if (mode === "full" || mode === "full_fallback") {
+	if (mode === "full" || mode === "baseline_fallback") {
 		setTrust(knowledge, pathKey, scopeKey, servedHash, seq);
 		if (blockedRangesByPath && isRangeScope(scopeKey)) {
 			clearRangeBlocker(blockedRangesByPath, pathKey, scopeKey);

package/src/telemetry.ts

@@ -19,7 +19,7 @@ function createModeCounts(): ReadCacheModeCounts {
 		unchanged: 0,
 		unchanged_range: 0,
 		diff: 0,
-		full_fallback: 0,
+		baseline_fallback: 0,
 	};
 }
 

package/src/tool.ts

@@ -50,12 +50,18 @@ export const readToolSchema = Type.Object({
 	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
 	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
 	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+	bypass_cache: Type.Optional(
+		Type.Boolean({
+			description:
+				"If true, bypass readcache optimization for this call and return baseline read output for the requested scope",
+		}),
+	),
 });
 
 export type ReadToolParams = Static<typeof readToolSchema>;
 
 function buildReadDescription(): string {
-	return `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. Returns full text, unchanged marker, or unified diff. Treat output as authoritative for requested scope. Use readcache_refresh only when output is insufficient for correctness; it forces full baseline payload for file and increases repeated-read context usage.`;
+	return `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. Returns full text, unchanged marker, or unified diff. Treat output as authoritative for requested scope. Set bypass_cache=true to force baseline output for this call only. If an edit fails because exact old text was not found, re-read the same path and scope with bypass_cache=true before retrying edit. Use readcache_refresh only when output is insufficient for correctness across calls; it invalidates trust for the selected scope until that scope is re-anchored by a baseline read, and increases repeated-read context usage.`;
 }
 
 function hasImageContent(result: AgentToolResult<ReadToolDetails | undefined>): boolean {
@@ -302,6 +308,24 @@ export function createReadOverrideTool(runtimeState: ReplayRuntimeState = create
 			throwIfAborted(signal);
 			const pathKey = parsed.absolutePath;
 			const scopeKey = scopeKeyForRange(start, end, totalLines);
+
+			if (params.bypass_cache === true) {
+				const meta = buildReadcacheMeta(
+					pathKey,
+					scopeKey,
+					current.currentHash,
+					"full",
+					totalLines,
+					start,
+					end,
+					current.bytes.byteLength,
+					undefined,
+					buildDebugInfo(scopeKey, undefined, "bypass_cache"),
+				);
+				await persistAndOverlay(runtimeState, ctx, pathKey, scopeKey, current.currentHash, current.text);
+				return attachMetaToBaseline(baselineResult, meta);
+			}
+
 			const knowledge = buildKnowledgeForLeaf(ctx.sessionManager, runtimeState);
 			const pathKnowledge = knowledge.get(pathKey);
 			const rangeScopeBlocked = isRangeScopeBlockedByInvalidation(
@@ -366,7 +390,7 @@ export function createReadOverrideTool(runtimeState: ReplayRuntimeState = create
 					pathKey,
 					scopeKey,
 					current.currentHash,
-					"full_fallback",
+					"baseline_fallback",
 					totalLines,
 					start,
 					end,

package/src/types.ts

@@ -10,7 +10,7 @@ export interface ScopeTrust {
 	seq: number;
 }
 
-export type ReadCacheMode = "full" | "unchanged" | "unchanged_range" | "diff" | "full_fallback";
+export type ReadCacheMode = "full" | "unchanged" | "unchanged_range" | "diff" | "baseline_fallback";
 
 export type ReadCacheDebugReason =
 	| "no_base_hash"
@@ -23,7 +23,8 @@ export type ReadCacheDebugReason =
 	| "diff_unavailable_or_empty"
 	| "diff_not_useful"
 	| "diff_payload_truncated"
-	| "diff_emitted";
+	| "diff_emitted"
+	| "bypass_cache";
 
 export interface ReadCacheDebugV1 {
 	reason: ReadCacheDebugReason;