pi-lean-ctx 3.8.6 → 3.8.8

package/extensions/config.ts

@@ -132,6 +132,32 @@ export function resolveRouteShell(mode: PiMode, fileRouteShell: unknown): boolea
   return fileRouteShell === true;
 }
 
+/**
+ * The five Pi builtins lean-ctx ships compressed `ctx_*` replacements for.
+ * Suppressing one removes it from the agent's tool set, so the agent must reach
+ * for the metered ctx_* equivalent instead of the uncompressed native.
+ */
+export const REPLACEABLE_BUILTIN_TOOLS = ["read", "bash", "ls", "find", "grep"] as const;
+
+/**
+ * The Pi builtins to suppress for a resolved config. Single source of truth for
+ * the R1 "102 native bash / 0 ctx_shell" fix (#361): whenever the returned set
+ * contains `bash`, the native shell is gone and the agent must route through
+ * `ctx_shell` (compressed + metered).
+ *
+ *   replace             → all five natives suppressed (only ctx_* exposed)
+ *   additive+routeShell → only `bash` suppressed (read/ls/find/grep stay)
+ *   additive            → nothing suppressed (fully non-regressive default)
+ *
+ * Invariant: every suppressed name has a ctx_* replacement (a subset of
+ * REPLACEABLE_BUILTIN_TOOLS), so a builtin is never removed without a substitute.
+ */
+export function resolveSuppressedBuiltins(mode: PiMode, routeShell: boolean): Set<string> {
+  if (mode === "replace") return new Set(REPLACEABLE_BUILTIN_TOOLS);
+  if (routeShell) return new Set(["bash"]);
+  return new Set<string>();
+}
+
 /** Split a comma/whitespace-separated tool list into trimmed, non-empty names. */
 function parseToolList(raw: string | undefined): string[] {
   if (!raw) return [];

package/extensions/index.ts

@@ -22,7 +22,7 @@ import { readFile, stat } from "node:fs/promises";
 import { extname, resolve } from "node:path";
 import { homedir, platform } from "node:os";
 import { McpBridge } from "./mcp-bridge.js";
-import { loadPiConfig } from "./config.js";
+import { loadPiConfig, resolveSuppressedBuiltins } from "./config.js";
 import type { CompressionStats } from "./types.js";
 
 const CODE_EXTENSIONS = new Set([
@@ -44,12 +44,12 @@ const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
 const CODE_FULL_READ_MAX_BYTES = 8 * 1024;
 const CODE_SIGNATURES_MIN_BYTES = 96 * 1024;
 
-// Pi builtins that can be replaced with ctx_ prefixed versions.
-// Settings resolve from (most explicit first): LEAN_CTX_PI_* env vars, then
-// ~/.pi/agent/extensions/pi-lean-ctx/config.json, then defaults (issue #344).
+// Which Pi builtins to suppress is resolved by resolveSuppressedBuiltins (in
+// config.ts, unit-tested). Settings resolve from (most explicit first):
+// LEAN_CTX_PI_* env vars, then ~/.pi/agent/extensions/pi-lean-ctx/config.json,
+// then defaults (issue #344).
 //   mode "additive" (default) — keep Pi builtins, add ctx_* alongside
 //   mode "replace"            — disable Pi builtins, only expose ctx_*
-const DISABLED_BUILTIN_TOOLS = new Set(["read", "bash", "ls", "find", "grep"]);
 const PI_CONFIG = loadPiConfig();
 const PI_MODE = PI_CONFIG.mode;
 // Max bytes constant for truncation warnings (same as Pi's DEFAULT_MAX_BYTES)
@@ -61,11 +61,17 @@ const readModeSchema = Type.Union([
   Type.Literal("signatures"),
 ], { description: "Override auto-selection: full (complete content), map (deps+API signatures), signatures (AST only)" });
 
+// Kept field-compatible with the canonical MCP `ctx_read` schema (registry in
+// rust/src/tools/registered/ctx_read.rs) so the tool looks identical across
+// harnesses: Codex sees `start_line`/`fresh`, Pi must too (GH #432). `offset` is
+// the historical Pi alias for `start_line`; both are accepted.
 const readSchema = 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" })),
   mode: Type.Optional(readModeSchema),
+  start_line: Type.Optional(Type.Number({ description: "1-based line to start reading from (alias: offset)" })),
+  offset: Type.Optional(Type.Number({ description: "Alias for start_line — 1-based line to start reading from" })),
+  limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+  fresh: Type.Optional(Type.Boolean({ description: "Force a fresh disk re-read, bypassing the session cache" })),
 });
 
 // `path` is REQUIRED on ls/find/grep (#395): with an optional path these tools
@@ -343,11 +349,7 @@ export default async function (pi: ExtensionAPI) {
   //     finding: 102 bash / 0 ctx_shell), so the heaviest addressable surface in
   //     a fix task — make/reproducer/test logs — never reaches the compressor.
   //   - "additive" without routeShell → suppress nothing (keep Pi builtins).
-  const suppressedBuiltins = PI_MODE === "replace"
-    ? DISABLED_BUILTIN_TOOLS
-    : PI_CONFIG.routeShell
-      ? new Set(["bash"])
-      : new Set<string>();
+  const suppressedBuiltins = resolveSuppressedBuiltins(PI_MODE, PI_CONFIG.routeShell);
 
   if (suppressedBuiltins.size > 0) {
     pi.on("session_start", () => {
@@ -555,17 +557,22 @@ export default async function (pi: ExtensionAPI) {
       const requestedPath = normalizePathArg(params.path);
       const absolutePath = resolve(ctx.cwd, requestedPath);
 
-      if (params.offset !== undefined || params.limit !== undefined) {
-        const startLine = params.offset ?? 1;
+      // `start_line` is the canonical name; `offset` is the historical Pi alias
+      // (GH #432). `fresh` forces a disk re-read past the session cache.
+      const startOffset = params.offset ?? params.start_line;
+      const forceFresh = params.fresh === true;
+
+      if (startOffset !== undefined || params.limit !== undefined) {
+        const startLine = startOffset ?? 1;
         const endLine = params.limit ? startLine + params.limit - 1 : 999999;
         const mode = `lines:${startLine}-${endLine}`;
         // Route line-range reads through the bridge too, so re-reading the same
         // slice hits the session cache instead of re-spawning a CLI per call (#361).
         if (mcpBridge?.isConnected()) {
           try {
-            const bridged = await mcpBridge.callTool("ctx_read", { path: absolutePath, mode }, signal);
+            const bridged = await mcpBridge.callTool("ctx_read", { path: absolutePath, mode, ...(forceFresh ? { fresh: true } : {}) }, signal);
             const bridgedText = bridged.content.map((block) => block.text).join("");
-            const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
+            const originalSlice = await readSlice(absolutePath, startOffset, params.limit);
             const decorated = withFooter(bridgedText, { originalText: originalSlice.text, always: true, preferEstimate: true, suppressIfNoSaving: true });
             return {
               content: [{ type: "text", text: decorated.text }],
@@ -575,17 +582,17 @@ export default async function (pi: ExtensionAPI) {
             console.error(`[pi-lean-ctx] ctx_read(${mode}) bridge call failed, falling back to CLI: ${err}`);
           }
         }
-        const args = ["read", absolutePath, "-m", mode];
+        const args = ["read", absolutePath, "-m", mode, ...(forceFresh ? ["--fresh"] : [])];
         try {
           const output = await execLeanCtx(pi, args);
-          const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
+          const originalSlice = await readSlice(absolutePath, startOffset, params.limit);
           const decorated = withFooter(output, { originalText: originalSlice.text, always: true, preferEstimate: true, suppressIfNoSaving: true });
           return {
             content: [{ type: "text", text: decorated.text }],
             details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx", mode, compression: decorated.stats },
           };
         } catch {
-          const sliced = await readSlice(absolutePath, params.offset, params.limit);
+          const sliced = await readSlice(absolutePath, startOffset, params.limit);
           return {
             content: [{ type: "text", text: sliced.text }],
             details: { path: absolutePath, lines: sliced.lines, source: "local-slice-fallback", truncated: sliced.truncated },
@@ -598,6 +605,7 @@ export default async function (pi: ExtensionAPI) {
       }
 
       const isExplicitFull = params.mode === "full";
+      const wantsFresh = forceFresh || isExplicitFull;
       const mode = params.mode ?? await chooseReadMode(absolutePath);
 
       // When the embedded MCP bridge is connected, route the read through it so
@@ -611,7 +619,7 @@ export default async function (pi: ExtensionAPI) {
         try {
           const bridged = await mcpBridge.callTool(
             "ctx_read",
-            { path: absolutePath, mode, ...(isExplicitFull ? { fresh: true } : {}) },
+            { path: absolutePath, mode, ...(wantsFresh ? { fresh: true } : {}) },
             signal,
           );
           const bridgedText = bridged.content.map((block) => block.text).join("");
@@ -626,7 +634,7 @@ export default async function (pi: ExtensionAPI) {
         }
       }
 
-      const args = ["read", absolutePath, "-m", mode, ...(isExplicitFull ? ["--fresh"] : [])];
+      const args = ["read", absolutePath, "-m", mode, ...(wantsFresh ? ["--fresh"] : [])];
       const output = await execLeanCtx(pi, args);
       const originalText = await readFile(absolutePath, "utf8");
       const decorated = withFooter(output, { originalText, always: true, preferEstimate: true, suppressIfNoSaving: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.8.6",
+  "version": "3.8.8",
   "description": "Pi Coding Agent extension — routes bash/read/grep/find/ls through lean-ctx for strong token savings. The embedded MCP bridge (on by default) adds a persistent session cache so unchanged re-reads cost ~13 tokens.",
   "keywords": [
     "pi-package",