pi-lean-ctx 3.7.4 → 3.7.5

package/README.md

@@ -2,8 +2,8 @@
 
 [Pi Coding Agent](https://github.com/badlogic/pi-mono) extension that provides `ctx_`-prefixed tools backed by [lean-ctx](https://leanctx.com) for **60–90% token savings**.
 
-- **Default**: CLI-only, additive mode (no MCP required, Pi builtins preserved)
-- **Optional**: enable MCP tools (`LEAN_CTX_PI_ENABLE_MCP=1`) or run `lean-ctx init --agent pi --mode mcp`
+- **Default**: embedded MCP bridge ON (persistent session cache → unchanged re-reads cost ~13 tokens), additive mode (Pi builtins preserved)
+- **Opt out**: `LEAN_CTX_PI_ENABLE_MCP=0` (or `"enableMcp": false`) forces the one-shot CLI path, which cannot cache across calls
 - **Optional**: replace mode (`LEAN_CTX_PI_MODE=replace`) disables Pi builtins
 
 ## Tool Mode
@@ -108,32 +108,37 @@ These tools invoke the `lean-ctx` binary via CLI with `LEAN_CTX_COMPRESS=1`.
 The built-in tools they replace (`read`, `bash`, `ls`, `find`, `grep`) are disabled
 via `pi.setActiveTools()` so only the `ctx_` versions are available to the LLM.
 
-### Optional MCP bridge (all other tools)
+### Embedded MCP bridge (session cache + advanced tools)
 
-If you enable the MCP bridge, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio).
-It discovers available tools via `list_tools`, filters out those already covered by `ctx_` CLI tools,
-and registers the rest as native Pi tools.
+On by default, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio).
+This persistent process holds the **session cache**: `ctx_read` (every mode, including line
+ranges) is routed through the bridge, so an unchanged re-read costs ~13 tokens instead of the
+full file and the read registers as a real CEP session (counted by `lean-ctx gain`). The bridge
+also discovers the server's advanced tools (`ctx_edit`, `ctx_overview`, `ctx_graph`, …),
+filters out those already exposed as `ctx_` CLI tools, and registers the rest as native Pi tools.
 
-If `lean-ctx` is already configured as an MCP server via [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) in `~/.pi/agent/mcp.json`, the embedded bridge is skipped to avoid duplicate tools.
+The bridge wins over `~/.pi/agent/mcp.json`: a `lean-ctx` entry there (written by
+`lean-ctx init --agent pi`) does **not** disable the embedded bridge, because Pi has no native
+MCP support and that entry only does anything if you separately run
+[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter). `/lean-ctx` warns about possible
+duplicates only when the adapter is genuinely running. If the bridge can't start, the CLI path
+keeps working — only the cache and advanced tools are unavailable.
 
 ### Automatic reconnection
 
 If the MCP server process crashes, the bridge automatically reconnects (up to 3 attempts with exponential backoff). If reconnection fails, CLI-based tools continue working normally — only the advanced MCP tools become unavailable.
 
-## Enabling MCP (optional)
+## Disabling the bridge (optional)
 
-Set an environment variable and restart Pi:
+The bridge is on by default. To force the one-shot CLI path (no cross-call cache),
+set an environment variable and restart Pi:
 
 ```bash
-export LEAN_CTX_PI_ENABLE_MCP=1
+export LEAN_CTX_PI_ENABLE_MCP=0
 pi
 ```
 
-Or configure MCP via `lean-ctx init`:
-
-```bash
-lean-ctx init --agent pi --mode mcp
-```
+…or set `"enableMcp": false` in `~/.pi/agent/extensions/pi-lean-ctx/config.json`.
 
 ## pi-mcp-adapter compatibility
 

package/extensions/config.ts

@@ -15,7 +15,11 @@ import { resolve } from "node:path";
 export interface PiLeanCtxFileConfig {
   /** Tool exposure: "additive" (Pi builtins + ctx_*) or "replace" (ctx_* only). */
   mode?: string;
-  /** Start the embedded MCP bridge (equivalent to `LEAN_CTX_PI_ENABLE_MCP=1`). */
+  /**
+   * Start the embedded MCP bridge (the persistent session cache). Default
+   * `true`; set `false` (or `LEAN_CTX_PI_ENABLE_MCP=0`) to force the one-shot
+   * CLI path, which cannot cache across calls.
+   */
   enableMcp?: boolean;
   /** Absolute path to the lean-ctx binary (equivalent to `LEAN_CTX_BIN`). */
   binary?: string;
@@ -94,10 +98,15 @@ export function loadPiConfig(): ResolvedPiConfig {
   const configPath = piConfigPath();
   const { cfg, loaded } = readFileConfig(configPath);
 
+  // The embedded MCP bridge holds the persistent session cache, so unchanged
+  // re-reads cost ~13 tokens and reads register as CEP sessions. That is
+  // lean-ctx's core value prop, so the bridge is ON by default; the one-shot CLI
+  // path cannot cache across calls (#361). Opt out with LEAN_CTX_PI_ENABLE_MCP=0
+  // or "enableMcp": false in config.json.
   const enableMcp =
     process.env.LEAN_CTX_PI_ENABLE_MCP !== undefined
       ? envFlag("LEAN_CTX_PI_ENABLE_MCP")
-      : cfg.enableMcp === true;
+      : cfg.enableMcp !== false;
 
   const forwardedEnv: Record<string, string> = {};
   if (cfg.env && typeof cfg.env === "object" && !Array.isArray(cfg.env)) {

package/extensions/index.ts

@@ -327,6 +327,11 @@ export default async function (pi: ExtensionAPI) {
     });
   }
 
+  // Declared up-front so the ctx_read handler (registered below) can route
+  // through the embedded bridge once it connects. Assigned after the tools are
+  // registered (the bridge is started at the end of this function).
+  let mcpBridge: McpBridge | null = null;
+
   const baseBashTool = createBashToolDefinition(process.cwd(), {
     spawnHook: ({ command, cwd, env }) => {
       const bin = resolveBinary();
@@ -351,7 +356,7 @@ export default async function (pi: ExtensionAPI) {
     name: "ctx_shell",
     label: "ctx_shell",
     description:
-      "Execute a shell command. Output is auto-compressed by lean-ctx. "
+      "Run shell commands. Prefer over native Bash/shell (auto-compressed output). "
       + "IMPORTANT: Do NOT use ctx_shell to read files (cat/head/tail) — use ctx_read instead. "
       + "Do NOT use ctx_shell for grep/find/ls — use ctx_grep, ctx_find, ctx_ls. "
       + "Set raw=true to skip compression when exact output matters. "
@@ -412,10 +417,11 @@ export default async function (pi: ExtensionAPI) {
     name: "ctx_read",
     label: "ctx_read",
     description:
-      "Read file contents. ALWAYS use ctx_read instead of cat/head/tail via ctx_shell. "
+      "Read a file. Prefer over native Read/cat/head/tail (cached, compressed). "
+      + "Unchanged re-reads cost ~13 tokens. "
       + "Auto-selects mode: configs (.yaml/.json/.toml/.env) are always full-read. "
       + "Code files: full (<8KB), map (8-96KB), signatures (>96KB). "
-      + "Add mode=full to get complete file content (bypasses cache). "
+      + "Add mode=full to get complete file content. "
       + "Use offset and limit to read specific line ranges.",
     promptSnippet: "Read file contents (always use instead of cat)",
     promptGuidelines: [
@@ -491,14 +497,31 @@ export default async function (pi: ExtensionAPI) {
       if (params.offset !== undefined || params.limit !== undefined) {
         const startLine = params.offset ?? 1;
         const endLine = params.limit ? startLine + params.limit - 1 : 999999;
-        const args = ["read", absolutePath, "-m", `lines:${startLine}-${endLine}`];
+        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 bridgedText = bridged.content.map((block) => block.text).join("");
+            const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
+            const decorated = withFooter(bridgedText, { originalText: originalSlice.text, always: true, preferEstimate: true });
+            return {
+              content: [{ type: "text", text: decorated.text }],
+              details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx-bridge", mode, compression: decorated.stats },
+            };
+          } catch (err) {
+            console.error(`[pi-lean-ctx] ctx_read(${mode}) bridge call failed, falling back to CLI: ${err}`);
+          }
+        }
+        const args = ["read", absolutePath, "-m", mode];
         try {
           const output = await execLeanCtx(pi, args);
           const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
           const decorated = withFooter(output, { originalText: originalSlice.text, always: true, preferEstimate: true });
           return {
             content: [{ type: "text", text: decorated.text }],
-            details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx", mode: `lines:${startLine}-${endLine}`, compression: decorated.stats },
+            details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx", mode, compression: decorated.stats },
           };
         } catch {
           const sliced = await readSlice(absolutePath, params.offset, params.limit);
@@ -515,6 +538,33 @@ export default async function (pi: ExtensionAPI) {
 
       const isExplicitFull = params.mode === "full";
       const mode = params.mode ?? await chooseReadMode(absolutePath);
+
+      // When the embedded MCP bridge is connected, route the read through it so
+      // the persistent session cache engages: an unchanged re-read then costs
+      // ~13 tokens instead of the full file, and the read registers as a real
+      // CEP session (counted by `lean-ctx gain`). The one-shot CLI path below
+      // spawns a fresh `lean-ctx read` per call and therefore cannot cache
+      // across calls — it is used only as a fallback when the bridge is
+      // unavailable or errors.
+      if (mcpBridge?.isConnected()) {
+        try {
+          const bridged = await mcpBridge.callTool(
+            "ctx_read",
+            { path: absolutePath, mode, ...(isExplicitFull ? { fresh: true } : {}) },
+            signal,
+          );
+          const bridgedText = bridged.content.map((block) => block.text).join("");
+          const originalText = await readFile(absolutePath, "utf8");
+          const decorated = withFooter(bridgedText, { originalText, always: true, preferEstimate: true });
+          return {
+            content: [{ type: "text", text: decorated.text }],
+            details: { path: absolutePath, source: "lean-ctx-bridge", mode, compression: decorated.stats },
+          };
+        } catch (err) {
+          console.error(`[pi-lean-ctx] ctx_read bridge call failed, falling back to CLI: ${err}`);
+        }
+      }
+
       const args = ["read", absolutePath, "-m", mode, ...(isExplicitFull ? ["--fresh"] : [])];
       const output = await execLeanCtx(pi, args);
       const originalText = await readFile(absolutePath, "utf8");
@@ -531,7 +581,7 @@ export default async function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "ctx_ls",
     label: "ctx_ls",
-    description: "List directory contents. Use limit to reduce output size.",
+    description: "List a directory. Prefer over native ls (compact, summarized). Use limit to reduce output size.",
     promptSnippet: "List directory contents",
     parameters: lsSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -550,7 +600,7 @@ export default async function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "ctx_find",
     label: "ctx_find",
-    description: "Find files by glob pattern (respects .gitignore). Use limit to reduce output size.",
+    description: "Find files by glob. Prefer over native find/fd (gitignore-aware). Use limit to reduce output size.",
     promptSnippet: "Find files by glob pattern",
     parameters: findSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -569,7 +619,7 @@ export default async function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "ctx_grep",
     label: "ctx_grep",
-    description: "Search file contents with ripgrep. Use limit to cap matches and context for surrounding lines.",
+    description: "Search code. Prefer over native Grep/ripgrep (compact, ranked). Use limit to cap matches, context for surrounding lines.",
     promptSnippet: "Search file contents for patterns",
     parameters: grepSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -623,7 +673,7 @@ export default async function (pi: ExtensionAPI) {
   // is actually serving it — pi has no native MCP support, and `lean-ctx init
   // --agent pi` writes that entry by default — so it must not silently disable the
   // bridge a user explicitly requested via LEAN_CTX_PI_ENABLE_MCP=1 / enableMcp.
-  const mcpBridge = enableMcpBridge
+  mcpBridge = enableMcpBridge
     ? new McpBridge(resolveBinary(), PI_CONFIG.forwardedEnv)
     : null;
 

package/extensions/mcp-bridge.ts

@@ -341,6 +341,11 @@ export class McpBridge {
     return Type.Object(fields);
   }
 
+  /** True when the MCP client is connected and able to serve tool calls. */
+  isConnected(): boolean {
+    return this.connected && this.client !== null;
+  }
+
   getStatus(): McpBridgeStatus {
     return {
       mode: "embedded",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.7.4",
-  "description": "Pi Coding Agent extension (CLI-first) \u2014 routes bash/read/grep/find/ls through lean-ctx CLI for strong token savings. Optional MCP bridge can register advanced tools.",
+  "version": "3.7.5",
+  "description": "Pi Coding Agent extension \u2014 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",
     "lean-ctx",