pi-lean-ctx 3.7.2 → 3.7.4

package/README.md

@@ -16,6 +16,25 @@ To switch to **replace mode** (disables Pi builtins, only `ctx_*` tools availabl
 export LEAN_CTX_PI_MODE=replace
 ```
 
+## Config file
+
+If you only use lean-ctx through Pi, keep every setting in one file instead of
+env vars — `~/.pi/agent/extensions/pi-lean-ctx/config.json`:
+
+```json
+{
+  "mode": "replace",
+  "enableMcp": true,
+  "binary": "/opt/lean-ctx/bin/lean-ctx",
+  "env": { "LEAN_CTX_COMPRESSION": "aggressive" }
+}
+```
+
+`mode` → `LEAN_CTX_PI_MODE`, `enableMcp` → `LEAN_CTX_PI_ENABLE_MCP`,
+`binary` → `LEAN_CTX_BIN`. The `env` map is forwarded to every `lean-ctx`
+subprocess, so it can override `~/.lean-ctx/config.toml` engine settings.
+Explicit env vars still win over the file; the file wins over defaults.
+
 ## What it does
 
 ### ctx_ Tools (CLI-backed)
@@ -146,10 +165,11 @@ When pi-mcp-adapter manages the lean-ctx MCP server, pi-lean-ctx detects this an
 The extension locates the `lean-ctx` binary in this order:
 
 1. `LEAN_CTX_BIN` environment variable
-2. `~/.cargo/bin/lean-ctx`
-3. `~/.local/bin/lean-ctx` (Linux) or `%APPDATA%\Local\lean-ctx\lean-ctx.exe` (Windows)
-4. `/usr/local/bin/lean-ctx` (macOS/Linux)
-5. `lean-ctx` on PATH
+2. `binary` in `~/.pi/agent/extensions/pi-lean-ctx/config.json`
+3. `~/.cargo/bin/lean-ctx`
+4. `~/.local/bin/lean-ctx` (Linux) or `%APPDATA%\Local\lean-ctx\lean-ctx.exe` (Windows)
+5. `/usr/local/bin/lean-ctx` (macOS/Linux)
+6. `lean-ctx` on PATH
 
 ## Smart Read Modes
 

package/extensions/config.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+/**
+ * Shape of the optional Pi override file
+ * `~/.pi/agent/extensions/pi-lean-ctx/config.json`.
+ *
+ * It lets users who only run lean-ctx through Pi keep every setting inside
+ * their Pi configuration instead of juggling `LEAN_CTX_PI_*` environment
+ * variables and `~/.lean-ctx/config.toml` (see issue #344). All fields are
+ * optional; an absent or malformed file simply falls back to env vars and
+ * built-in defaults.
+ */
+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`). */
+  enableMcp?: boolean;
+  /** Absolute path to the lean-ctx binary (equivalent to `LEAN_CTX_BIN`). */
+  binary?: string;
+  /**
+   * Extra environment forwarded to every lean-ctx subprocess. Use this to
+   * override `~/.lean-ctx/config.toml` engine settings without touching that
+   * file, since the engine honours `LEAN_CTX_*` env vars
+   * (e.g. `{ "LEAN_CTX_COMPRESSION": "aggressive" }`).
+   */
+  env?: Record<string, string>;
+}
+
+export type PiMode = "additive" | "replace";
+
+/** Fully resolved configuration after merging file, env vars and defaults. */
+export interface ResolvedPiConfig {
+  mode: PiMode;
+  enableMcp: boolean;
+  /** Binary path from the file; `LEAN_CTX_BIN` still takes precedence at use time. */
+  binaryOverride?: string;
+  /** Engine env overrides forwarded to lean-ctx subprocesses. */
+  forwardedEnv: Record<string, string>;
+  /** Absolute path the loader looked at (whether or not it existed). */
+  configPath: string;
+  /** True when the file existed and parsed into a JSON object. */
+  loaded: boolean;
+}
+
+/** Absolute path to the Pi override file (Pi's per-extension config convention). */
+export function piConfigPath(): string {
+  return resolve(
+    homedir(),
+    ".pi",
+    "agent",
+    "extensions",
+    "pi-lean-ctx",
+    "config.json",
+  );
+}
+
+function envFlag(name: string): boolean {
+  const raw = process.env[name];
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+function readFileConfig(path: string): { cfg: PiLeanCtxFileConfig; loaded: boolean } {
+  if (!existsSync(path)) return { cfg: {}, loaded: false };
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { cfg: parsed as PiLeanCtxFileConfig, loaded: true };
+    }
+    console.error(`[pi-lean-ctx] ${path}: expected a JSON object — ignoring.`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[pi-lean-ctx] ${path}: invalid JSON (${msg}) — ignoring.`);
+  }
+  return { cfg: {}, loaded: false };
+}
+
+function resolveMode(fileMode: string | undefined): PiMode {
+  const raw = (process.env.LEAN_CTX_PI_MODE ?? fileMode ?? "additive").toLowerCase();
+  return raw === "replace" ? "replace" : "additive";
+}
+
+/**
+ * Loads and resolves the Pi override config. Precedence per setting is
+ * "most explicit wins": an explicit `LEAN_CTX_PI_*` / `LEAN_CTX_BIN` env var
+ * overrides `config.json`, which overrides the built-in default. This keeps
+ * shareable, file-only setups working (no env vars needed) while still
+ * allowing ad-hoc env overrides on a single machine.
+ */
+export function loadPiConfig(): ResolvedPiConfig {
+  const configPath = piConfigPath();
+  const { cfg, loaded } = readFileConfig(configPath);
+
+  const enableMcp =
+    process.env.LEAN_CTX_PI_ENABLE_MCP !== undefined
+      ? envFlag("LEAN_CTX_PI_ENABLE_MCP")
+      : cfg.enableMcp === true;
+
+  const forwardedEnv: Record<string, string> = {};
+  if (cfg.env && typeof cfg.env === "object" && !Array.isArray(cfg.env)) {
+    for (const [key, value] of Object.entries(cfg.env)) {
+      if (typeof value === "string") forwardedEnv[key] = value;
+    }
+  }
+
+  const binaryOverride =
+    typeof cfg.binary === "string" && cfg.binary.length > 0 ? cfg.binary : undefined;
+
+  return {
+    mode: resolveMode(cfg.mode),
+    enableMcp,
+    binaryOverride,
+    forwardedEnv,
+    configPath,
+    loaded,
+  };
+}

package/extensions/index.ts

@@ -1,4 +1,9 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  AgentToolResult,
+  BashToolDetails,
+  ExtensionAPI,
+  ReadToolDetails,
+} from "@earendil-works/pi-coding-agent";
 import {
   createBashToolDefinition,
   createReadToolDefinition,
@@ -8,12 +13,13 @@ import {
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 import { existsSync, readFileSync } from "node:fs";
 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 type { CompressionStats } from "./types.js";
 
 const CODE_EXTENSIONS = new Set([
@@ -36,11 +42,13 @@ 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_*
+// 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_MODE = (process.env.LEAN_CTX_PI_MODE || "additive").toLowerCase();
+const PI_CONFIG = loadPiConfig();
+const PI_MODE = PI_CONFIG.mode;
 // Max bytes constant for truncation warnings (same as Pi's DEFAULT_MAX_BYTES)
 const DEFAULT_MAX_BYTES = 8192;
 
@@ -93,16 +101,23 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-function envFlag(name: string): boolean {
-  const raw = process.env[name];
-  if (!raw) return false;
-  const v = raw.trim().toLowerCase();
-  return v === "1" || v === "true" || v === "yes" || v === "on";
+// Environment for every lean-ctx subprocess: config.json `env` overrides
+// (lowest precedence) < the caller's env < the flags lean-ctx must always see.
+function leanCtxEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return {
+    ...PI_CONFIG.forwardedEnv,
+    ...base,
+    LEAN_CTX_COMPRESS: "1",
+    LEAN_CTX_SAVINGS_FOOTER: "always",
+  };
 }
 
 function resolveBinary(): string {
   const envBin = process.env.LEAN_CTX_BIN;
   if (envBin && existsSync(envBin)) return envBin;
+  if (PI_CONFIG.binaryOverride && existsSync(PI_CONFIG.binaryOverride)) {
+    return PI_CONFIG.binaryOverride;
+  }
 
   const home = homedir();
   const isWin = platform() === "win32";
@@ -282,7 +297,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", LEAN_CTX_SAVINGS_FOOTER: "always" } });
+  const result = await pi.exec(bin, args);
   if (result.code !== 0) {
     const msg = (result.stderr || result.stdout || `lean-ctx failed: ${args.join(" ")}`).trim();
     throw new Error(msg);
@@ -291,6 +306,17 @@ async function execLeanCtx(pi: ExtensionAPI, args: string[]) {
 }
 
 export default async function (pi: ExtensionAPI) {
+  // pi.exec()'s ExecOptions carries no `env`, so lean-ctx subprocesses inherit
+  // THIS process's environment. Seed it once with the config.json `env` overrides
+  // (issue #344) plus the flags lean-ctx must always see, so every path — pi.exec,
+  // the bash spawnHook, and the MCP bridge — shares one environment. An explicitly
+  // set environment variable always wins over the config file.
+  for (const [key, value] of Object.entries(PI_CONFIG.forwardedEnv)) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+  process.env.LEAN_CTX_COMPRESS = "1";
+  process.env.LEAN_CTX_SAVINGS_FOOTER ??= "always";
+
   // 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.
@@ -307,7 +333,7 @@ export default async function (pi: ExtensionAPI) {
       return {
         command: `${shellQuote(bin)} -c ${shellQuote(command)}`,
         cwd,
-        env: { ...env, LEAN_CTX_COMPRESS: "1", LEAN_CTX_SAVINGS_FOOTER: "always" },
+        env: leanCtxEnv(env),
       };
     },
   });
@@ -341,8 +367,15 @@ export default async function (pi: ExtensionAPI) {
         : (context.lastComponent ?? new Text("", 0, 0));
     },
     renderResult(result, options, theme, context) {
+      // ctx_shell wraps Pi's bash tool; its renderer is typed for BashToolDetails,
+      // while our result adds compression stats on top of the same shape.
       return baseBashTool.renderResult
-        ? baseBashTool.renderResult(result, options, theme, context)
+        ? baseBashTool.renderResult(
+            result as AgentToolResult<BashToolDetails | undefined>,
+            options,
+            theme,
+            context,
+          )
         : (context.lastComponent ?? new Text("", 0, 0));
     },
     async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -397,8 +430,14 @@ export default async function (pi: ExtensionAPI) {
     },
     renderResult(result, options, theme, context) {
       if (result.content.some((block) => block.type === "image")) {
+        // Reuse Pi's read renderer for images; its detail type is ReadToolDetails.
         return nativeReadTool.renderResult
-          ? nativeReadTool.renderResult(result, options, theme, context)
+          ? nativeReadTool.renderResult(
+              result as AgentToolResult<ReadToolDetails | undefined>,
+              options,
+              theme,
+              context,
+            )
           : (context.lastComponent ?? new Text("", 0, 0));
       }
 
@@ -438,7 +477,10 @@ export default async function (pi: ExtensionAPI) {
         text += `\n\n${theme.fg("muted", footer)}`;
       }
 
-      const component = context.lastComponent ?? new Text("", 0, 0);
+      // setText only exists on Text; lastComponent is the wider Component type.
+      const component = context.lastComponent instanceof Text
+        ? context.lastComponent
+        : new Text("", 0, 0);
       component.setText(text);
       return component;
     },
@@ -542,7 +584,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", LEAN_CTX_SAVINGS_FOOTER: "always" } });
+      const result = await pi.exec(bin, ["-c", ...searchArgs]);
       if (result.code >= 2) {
         const msg = (result.stderr || result.stdout || `lean-ctx grep failed: ${params.pattern}`).trim();
         throw new Error(msg);
@@ -574,9 +616,16 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
-  const enableMcpBridge = envFlag("LEAN_CTX_PI_ENABLE_MCP");
+  const enableMcpBridge = PI_CONFIG.enableMcp;
   const adapterConfigured = isMcpAdapterConfigured();
-  const mcpBridge = enableMcpBridge && !adapterConfigured ? new McpBridge(resolveBinary()) : null;
+  // An explicit opt-in to the embedded bridge wins over mcp.json detection (#361).
+  // A `lean-ctx` entry in ~/.pi/agent/mcp.json does NOT prove that pi-mcp-adapter
+  // 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
+    ? new McpBridge(resolveBinary(), PI_CONFIG.forwardedEnv)
+    : null;
 
   if (mcpBridge) {
     try {
@@ -595,11 +644,13 @@ export default async function (pi: ExtensionAPI) {
 
       const lines: string[] = [];
       lines.push(found ? `Binary: ${bin}` : "Binary: NOT FOUND — install: cargo install lean-ctx");
-      if (adapterConfigured) {
-        lines.push("MCP bridge: adapter-configured (extension bridge disabled)");
-      } else if (!enableMcpBridge) {
+      if (PI_CONFIG.loaded) {
+        lines.push(`Config: ${PI_CONFIG.configPath}`);
+      }
+      lines.push(`Mode: ${PI_MODE}`);
+      if (!enableMcpBridge) {
         lines.push("MCP bridge: disabled (CLI-first)");
-        lines.push("  Enable: set LEAN_CTX_PI_ENABLE_MCP=1 and restart Pi");
+        lines.push('  Enable: LEAN_CTX_PI_ENABLE_MCP=1 or "enableMcp": true in config.json, then restart Pi');
       } else if (status) {
         lines.push(`MCP bridge: ${status.mode} (${status.connected ? "connected" : "disconnected"})`);
         lines.push(`Reconnect attempts: ${status.reconnectAttempts}`);
@@ -607,6 +658,11 @@ export default async function (pi: ExtensionAPI) {
         if (status.toolNames.length > 0) {
           lines.push(`  ${status.toolNames.join(", ")}`);
         }
+        if (adapterConfigured) {
+          lines.push(
+            "  Note: ~/.pi/agent/mcp.json also has a lean-ctx entry. The embedded bridge is serving tools; if you additionally run pi-mcp-adapter you may see duplicates.",
+          );
+        }
         if (status.lastHungTool) {
           lines.push(`Last hung tool: ${status.lastHungTool}`);
         }

package/extensions/mcp-bridge.ts

@@ -1,9 +1,12 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { type TSchema, Type } from "typebox";
 import type { McpBridgeRetryState, McpBridgeStatus } from "./types.js";
 
+/** Result shape returned by the MCP client's `callTool`. */
+type McpCallResult = Awaited<ReturnType<Client["callTool"]>>;
+
 const CLI_OVERRIDE_TOOLS = new Set([
   "ctx_read",
   "ctx_multi_read",
@@ -56,13 +59,15 @@ export class McpBridge {
   private registeredTools: string[] = [];
   private connected = false;
   private binary: string;
+  private extraEnv: Record<string, string>;
   private reconnectAttempts = 0;
   private lastError: string | undefined;
   private lastHungTool: string | undefined;
   private lastRetry: McpBridgeRetryState | undefined;
 
-  constructor(binary: string) {
+  constructor(binary: string, extraEnv: Record<string, string> = {}) {
     this.binary = binary;
+    this.extraEnv = extraEnv;
   }
 
   async start(pi: ExtensionAPI): Promise<void> {
@@ -80,7 +85,8 @@ export class McpBridge {
     this.transport = new StdioClientTransport({
       command: this.binary,
       args: [],
-      env: { ...process.env, LEAN_CTX_COMPRESS: "1" },
+      // config.json `env` (lowest) < process env < the forced compress flag.
+      env: { ...this.extraEnv, ...process.env, LEAN_CTX_COMPRESS: "1" },
       stderr: "pipe",
     });
 
@@ -163,12 +169,14 @@ export class McpBridge {
       description: tool.description ?? `lean-ctx MCP tool: ${tool.name}`,
       promptSnippet: tool.description ?? tool.name,
       parameters: schema,
-      async execute(_toolCallId, params, signal) {
-        return bridge.callTool(
+      async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+        const result = await bridge.callTool(
           tool.name,
           params as Record<string, unknown>,
           signal,
         );
+        // Pi's AgentToolResult requires a `details` field; MCP tool output has none.
+        return { ...result, details: undefined };
       },
     });
 
@@ -179,7 +187,7 @@ export class McpBridge {
     name: string,
     args: Record<string, unknown>,
     signal?: AbortSignal,
-  ): Promise<{ content: Array<{ type: string; text: string }> }> {
+  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
     if (!this.client || !this.connected) {
       throw new Error(
         `lean-ctx MCP bridge not connected. Tool "${name}" unavailable.`,
@@ -221,7 +229,7 @@ export class McpBridge {
     name: string,
     args: Record<string, unknown>,
     signal?: AbortSignal,
-  ) {
+  ): Promise<McpCallResult> {
     const call = this.client?.callTool({ name, arguments: args });
     if (!call) {
       throw new Error(`lean-ctx MCP bridge not connected. Tool "${name}" unavailable.`);
@@ -239,7 +247,7 @@ export class McpBridge {
       }, TOOL_CALL_TIMEOUT_MS);
     });
 
-    const promises: Promise<unknown>[] = [call, timeout];
+    const promises: Promise<McpCallResult>[] = [call, timeout];
 
     if (signal) {
       let onAbort: (() => void) | undefined;
@@ -271,8 +279,8 @@ export class McpBridge {
   }
 
   private toTextBlocks(
-    result: Awaited<ReturnType<Client["callTool"]>>,
-  ): { content: Array<{ type: string; text: string }> } {
+    result: McpCallResult,
+  ): { content: Array<{ type: "text"; text: string }> } {
     const content = (
       result.content as Array<{ type: string; text?: string }>
     ).map((block) => ({
@@ -297,13 +305,13 @@ export class McpBridge {
     const required = new Set(
       (schema.required as string[] | undefined) ?? [],
     );
-    const fields: Record<string, ReturnType<typeof Type.String>> = {};
+    const fields: Record<string, TSchema> = {};
 
     for (const [key, prop] of Object.entries(properties)) {
       const desc = (prop.description as string) ?? undefined;
       const jsonType = prop.type as string | undefined;
 
-      let field;
+      let field: TSchema;
       switch (jsonType) {
         case "number":
         case "integer":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.7.2",
+  "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.",
   "keywords": [
     "pi-package",
@@ -25,8 +25,9 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.50.0",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "^1.0.0"
   },
   "pi": {
     "extensions": [