pi-lean-ctx 3.5.25 → 3.6.1

package/README.md

@@ -1,34 +1,47 @@
 # pi-lean-ctx
 
-CLI-first [Pi Coding Agent](https://github.com/badlogic/pi-mono) extension that routes Pi’s built-in tools through [lean-ctx](https://leanctx.com) for **60–90% token savings**.
+[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 (no MCP required)
+- **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`
+- **Optional**: replace mode (`LEAN_CTX_PI_MODE=replace`) disables Pi builtins
+
+## Tool Mode
+
+By default, pi-lean-ctx runs in **additive mode**: Pi's built-in tools (`read`, `bash`, `ls`, `find`, `grep`) remain available alongside the `ctx_*` tools. Agents can use either set.
+
+To switch to **replace mode** (disables Pi builtins, only `ctx_*` tools available):
+
+```bash
+export LEAN_CTX_PI_MODE=replace
+```
 
 ## What it does
 
-### Built-in Tool Overrides (CLI)
+### ctx_ Tools (CLI-backed)
 
-Overrides Pi's built-in tools to route them through `lean-ctx`:
+Adds `ctx_`-prefixed tools alongside Pi's builtins (or replaces them in `replace` mode):
 
-| Tool | Compression |
-|------|------------|
-| `bash` | All shell commands compressed via lean-ctx's 95+ patterns |
-| `read` | Smart mode selection (full/map/signatures) based on file type and size |
-| `grep` | Results grouped and compressed via ripgrep + lean-ctx |
-| `find` | File listings compressed and .gitignore-aware |
-| `ls` | Directory output compressed |
+| Tool | Replaces | Compression |
+|------|----------|-------------|
+| `ctx_read` | `read` | Smart mode selection (full/map/signatures) based on file type and size |
+| `ctx_shell` | `bash` | All shell commands compressed via lean-ctx's 95+ patterns |
+| `ctx_grep` | `grep` | Results grouped and compressed via ripgrep + lean-ctx |
+| `ctx_find` | `find` | File listings compressed and .gitignore-aware |
+| `ctx_ls` | `ls` | Directory output compressed |
+
+Pi's `edit` and `write` builtins remain unchanged.
 
 ### Direct lean-ctx CLI tool
 
-The extension registers a `lean_ctx` tool that runs `lean-ctx` directly (no nested compression).
+The `lean_ctx` tool runs `lean-ctx` directly (no nested compression).
 Use it for commands like:
 
-- `lean-ctx overview`
-- `lean-ctx session …`
-- `lean-ctx knowledge …`
-- `lean-ctx gain` / `lean-ctx stats`
-- `lean-ctx index …`
+- `lean_ctx overview`
+- `lean_ctx session …`
+- `lean_ctx knowledge …`
+- `lean_ctx gain` / `lean_ctx stats`
+- `lean_ctx index …`
 
 ### Optional MCP Tools (Embedded Bridge)
 
@@ -43,24 +56,11 @@ server and registers advanced tools directly in Pi:
 | `ctx_overview` | Codebase overview and architecture analysis |
 | `ctx_compress` | Manual compression control |
 | `ctx_metrics` | Token savings dashboard |
-| `ctx_agent` | Multi-agent coordination and handoffs |
-| `ctx_graph` | Dependency graph analysis |
-| `ctx_discover` | Smart code discovery |
-| `ctx_context` | Context window management |
-| `ctx_preload` | Predictive file preloading |
-| `ctx_delta` | Changed-lines-only reads |
-| `ctx_edit` | Read-modify-write in one call |
-| `ctx_dedup` | Duplicate context elimination |
-| `ctx_fill` | Template completion |
-| `ctx_intent` | Intent-based task routing |
-| `ctx_response` | Response optimization |
-| `ctx_wrapped` | Wrapped command execution |
-| `ctx_benchmark` | Compression benchmarking |
-| `ctx_analyze` | Code analysis |
-| `ctx_cache` | Cache management |
-| `ctx_execute` | Direct command execution |
-
-If you don’t want MCP: keep it disabled and use the CLI overrides + `lean_ctx` tool only.
+| `ctx_multi_read` | Batch file reads |
+| `ctx_search` | MCP-native search |
+| `ctx_tree` | File tree listing |
+
+If you don't want MCP: keep it disabled and use the `ctx_` CLI tools + `lean_ctx` tool only.
 
 ## Install
 
@@ -83,14 +83,17 @@ lean-ctx init --agent pi
 
 ## How it works
 
-### CLI overrides (bash, read, grep, find, ls)
+### ctx_ tools (CLI-backed)
 
-These tools invoke the `lean-ctx` binary via CLI with `LEAN_CTX_COMPRESS=1`. The output is parsed for compression stats and displayed with a token savings footer.
+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)
 
 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 CLI overrides, and registers the rest as native Pi tools.
+It discovers available tools via `list_tools`, filters out those already covered by `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.
 
@@ -150,7 +153,7 @@ The extension locates the `lean-ctx` binary in this order:
 
 ## Smart Read Modes
 
-The `read` tool automatically selects the optimal lean-ctx mode:
+The `ctx_read` tool automatically selects the optimal lean-ctx mode:
 
 | File Type | Size | Mode |
 |-----------|------|------|
@@ -166,7 +169,7 @@ The `read` tool automatically selects the optimal lean-ctx mode:
 Use `/lean-ctx` in Pi to check:
 - Which binary is being used
 - MCP bridge status (disabled / embedded / adapter)
-- Number and names of registered MCP tools
+- Active `ctx_` tool names
 
 ## Disabling specific tools
 

package/extensions/index.ts

@@ -1,14 +1,13 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   createBashToolDefinition,
   createReadToolDefinition,
-  DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   getLanguageFromPath,
   highlightCode,
   truncateHead,
-} from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { existsSync, readFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
@@ -36,10 +35,26 @@ 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.
+// LEAN_CTX_PI_MODE controls behavior:
+//   "additive" (default) — keep Pi builtins, add ctx_* alongside
+//   "replace"            — disable Pi builtins, only expose ctx_*
+const DISABLED_BUILTIN_TOOLS = new Set(["read", "bash", "ls", "find", "grep"]);
+const PI_MODE = (process.env.LEAN_CTX_PI_MODE || "additive").toLowerCase();
+// Max bytes constant for truncation warnings (same as Pi's DEFAULT_MAX_BYTES)
+const DEFAULT_MAX_BYTES = 8192;
+
+const readModeSchema = Type.Union([
+  Type.Literal("full"),
+  Type.Literal("map"),
+  Type.Literal("signatures"),
+], { description: "Override auto-selection: full (complete content), map (deps+API signatures), signatures (AST only)" });
+
 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),
 });
 
 const lsSchema = Type.Object({
@@ -267,7 +282,7 @@ function isMcpAdapterConfigured(): boolean {
 
 async function execLeanCtx(pi: ExtensionAPI, args: string[]) {
   const bin = resolveBinary();
-  const result = await pi.exec(bin, args, { env: { ...process.env, LEAN_CTX_COMPRESS: "1" } });
+  const result = await pi.exec(bin, args, { env: { ...process.env, LEAN_CTX_COMPRESS: "1", LEAN_CTX_SAVINGS_FOOTER: "always" } });
   if (result.code !== 0) {
     const msg = (result.stderr || result.stdout || `lean-ctx failed: ${args.join(" ")}`).trim();
     throw new Error(msg);
@@ -276,13 +291,23 @@ async function execLeanCtx(pi: ExtensionAPI, args: string[]) {
 }
 
 export default async function (pi: ExtensionAPI) {
+  // Defer setActiveTools to session_start — runtime actions aren't available during extension load
+  // In "replace" mode, disable Pi builtins and only expose ctx_* tools.
+  // In "additive" mode (default), keep Pi builtins alongside ctx_* tools.
+  if (PI_MODE === "replace") {
+    pi.on("session_start", () => {
+      const activeTools = pi.getActiveTools().filter((name) => !DISABLED_BUILTIN_TOOLS.has(name));
+      pi.setActiveTools(activeTools);
+    });
+  }
+
   const baseBashTool = createBashToolDefinition(process.cwd(), {
     spawnHook: ({ command, cwd, env }) => {
       const bin = resolveBinary();
       return {
-        command: `${shellQuote(bin)} -c sh -lc ${shellQuote(command)}`,
+        command: `${shellQuote(bin)} -c ${shellQuote(command)}`,
         cwd,
-        env: { ...env, LEAN_CTX_COMPRESS: "1" },
+        env: { ...env, LEAN_CTX_COMPRESS: "1", LEAN_CTX_SAVINGS_FOOTER: "always" },
       };
     },
   });
@@ -295,19 +320,31 @@ export default async function (pi: ExtensionAPI) {
     raw: Type.Optional(Type.Boolean({ description: "Skip compression, return full uncompressed output" })),
   });
 
+  // ── ctx_shell (replaces bash) ─────────────────────────────────────────
   pi.registerTool({
-    ...baseBashTool,
-    parameters: bashSchemaWithRaw,
+    name: "ctx_shell",
+    label: "ctx_shell",
     description:
-      "Execute a bash command. Output is auto-compressed by lean-ctx. "
-      + "IMPORTANT: Do NOT use bash to read files (cat/head/tail) — use the read tool instead. "
-      + "Do NOT use bash for grep/find/ls — use the dedicated tools. "
+      "Execute a shell command. Output is auto-compressed by lean-ctx. "
+      + "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. "
       + "Use timeout (seconds) to prevent hanging commands.",
-    promptSnippet: "Run shell commands (not for file reading — use read tool)",
+    promptSnippet: "Run shell commands (not for file reading — use ctx_read)",
     promptGuidelines: [
-      "Use bash only for commands with side effects: build, test, install, git, run scripts.",
+      "Use ctx_shell only for commands with side effects: build, test, install, git, run scripts.",
     ],
+    parameters: bashSchemaWithRaw,
+    renderCall(args, theme, context) {
+      return baseBashTool.renderCall
+        ? baseBashTool.renderCall(args, theme, context)
+        : (context.lastComponent ?? new Text("", 0, 0));
+    },
+    renderResult(result, options, theme, context) {
+      return baseBashTool.renderResult
+        ? baseBashTool.renderResult(result, options, theme, context)
+        : (context.lastComponent ?? new Text("", 0, 0));
+    },
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const isRaw = !!params.raw;
       const toolParams = { command: params.command, timeout: params.timeout };
@@ -335,19 +372,22 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  // ── ctx_read (replaces read) ──────────────────────────────────────────
   const nativeReadTool = createReadToolDefinition(process.cwd());
 
   pi.registerTool({
-    name: "read",
-    label: "Read",
+    name: "ctx_read",
+    label: "ctx_read",
     description:
-      "Read file contents. ALWAYS use this instead of cat/head/tail via bash. "
+      "Read file contents. ALWAYS use ctx_read instead of cat/head/tail via ctx_shell. "
       + "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). "
       + "Use offset and limit to read specific line ranges.",
     promptSnippet: "Read file contents (always use instead of cat)",
     promptGuidelines: [
-      "Use read to inspect file contents instead of cat or less.",
+      "Use ctx_read to inspect file contents instead of cat or less.",
+      "Use mode=full if you need the complete file content.",
     ],
     parameters: readSchema,
     renderCall(args, theme, context) {
@@ -386,11 +426,11 @@ export default async function (pi: ExtensionAPI) {
         | undefined;
       if (truncation?.truncated) {
         if (truncation.firstLineExceedsLimit) {
-          text += `\n${theme.fg("warning", `[First line exceeds ${Math.round((truncation.maxBytes ?? DEFAULT_MAX_BYTES) / 1024)}KB limit]`)}`;
+          text += `\n${theme.fg("warning", `[First line exceeds ${Math.round((truncation.maxBytes ?? 8192) / 1024)}KB limit]`)}`;
         } else if (truncation.truncatedBy === "lines") {
           text += `\n${theme.fg("warning", `[Truncated: ${truncation.outputLines} of ${truncation.totalLines} lines]`)}`;
         } else {
-          text += `\n${theme.fg("warning", `[Truncated: ${truncation.outputLines} lines (${Math.round((truncation.maxBytes ?? DEFAULT_MAX_BYTES) / 1024)}KB limit)]`)}`;
+          text += `\n${theme.fg("warning", `[Truncated: ${truncation.outputLines} lines (${Math.round((truncation.maxBytes ?? 8192) / 1024)}KB limit)]`)}`;
         }
       }
 
@@ -431,8 +471,9 @@ export default async function (pi: ExtensionAPI) {
         return nativeReadTool.execute(_toolCallId, { ...params, path: absolutePath }, signal, onUpdate, ctx);
       }
 
-      const mode = await chooseReadMode(absolutePath);
-      const args = mode === "full" ? ["read", absolutePath] : ["read", absolutePath, "-m", mode];
+      const isExplicitFull = params.mode === "full";
+      const mode = params.mode ?? await chooseReadMode(absolutePath);
+      const args = ["read", absolutePath, "-m", mode, ...(isExplicitFull ? ["--fresh"] : [])];
       const output = await execLeanCtx(pi, args);
       const originalText = await readFile(absolutePath, "utf8");
       const decorated = withFooter(output, { originalText, always: true, preferEstimate: true });
@@ -444,9 +485,10 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  // ── ctx_ls (replaces ls) ──────────────────────────────────────────────
   pi.registerTool({
-    name: "ls",
-    label: "ls",
+    name: "ctx_ls",
+    label: "ctx_ls",
     description: "List directory contents. Use limit to reduce output size.",
     promptSnippet: "List directory contents",
     parameters: lsSchema,
@@ -462,9 +504,10 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  // ── ctx_find (replaces find) ──────────────────────────────────────────
   pi.registerTool({
-    name: "find",
-    label: "find",
+    name: "ctx_find",
+    label: "ctx_find",
     description: "Find files by glob pattern (respects .gitignore). Use limit to reduce output size.",
     promptSnippet: "Find files by glob pattern",
     parameters: findSchema,
@@ -480,9 +523,10 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  // ── ctx_grep (replaces grep) ──────────────────────────────────────────
   pi.registerTool({
-    name: "grep",
-    label: "grep",
+    name: "ctx_grep",
+    label: "ctx_grep",
     description: "Search file contents with ripgrep. Use limit to cap matches and context for surrounding lines.",
     promptSnippet: "Search file contents for patterns",
     parameters: grepSchema,
@@ -498,7 +542,7 @@ export default async function (pi: ExtensionAPI) {
       searchArgs.push(params.pattern, absolutePath);
 
       const bin = resolveBinary();
-      const result = await pi.exec(bin, ["-c", ...searchArgs], { env: { ...process.env, LEAN_CTX_COMPRESS: "1" } });
+      const result = await pi.exec(bin, ["-c", ...searchArgs], { env: { ...process.env, LEAN_CTX_COMPRESS: "1", LEAN_CTX_SAVINGS_FOOTER: "always" } });
       if (result.code >= 2) {
         const msg = (result.stderr || result.stdout || `lean-ctx grep failed: ${params.pattern}`).trim();
         throw new Error(msg);
@@ -512,6 +556,7 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  // ── lean_ctx (CLI passthrough) ────────────────────────────────────────
   pi.registerTool({
     name: "lean_ctx",
     label: "lean_ctx",
@@ -575,6 +620,12 @@ export default async function (pi: ExtensionAPI) {
         }
       }
 
+      // Show active ctx_ tools
+      const ctxTools = pi.getActiveTools().filter((n) => n.startsWith("ctx_") || n === "lean_ctx");
+      if (ctxTools.length > 0) {
+        lines.push(`Active tools: ${ctxTools.join(", ")}`);
+      }
+
       const ok = found && (adapterConfigured || !enableMcpBridge || (status?.connected ?? false));
       ctx.ui.notify(lines.join("\n"), ok ? "info" : "warning");
     },

package/extensions/mcp-bridge.ts

@@ -1,6 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { McpBridgeRetryState, McpBridgeStatus } from "./types.js";
 
@@ -12,6 +12,8 @@ const CLI_OVERRIDE_TOOLS = new Set([
   "ctx_tree",
 ]);
 
+// No additional prefix filter — CLI_OVERRIDE_TOOLS covers exactly the tools we overwrite
+
 const MAX_RECONNECT_ATTEMPTS = 3;
 const RECONNECT_DELAY_MS = 2000;
 const TOOL_CALL_TIMEOUT_MS = 120000;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.5.25",
-  "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.6.1",
+  "description": "Pi Coding Agent extension (CLI-first) — routes bash/read/grep/find/ls through lean-ctx CLI for strong token savings. Optional MCP bridge can register advanced tools.",
   "keywords": [
     "pi-package",
     "lean-ctx",
@@ -25,8 +25,8 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.50.0",
-    "@mariozechner/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=0.50.0",
+    "@earendil-works/pi-tui": "*"
   },
   "pi": {
     "extensions": [
@@ -36,5 +36,8 @@
   "files": [
     "extensions/",
     "README.md"
-  ]
+  ],
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
 }