pi-read-map 1.2.4 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.0] - 2026-02-20
+
+### Changed
+
+- **Inline file maps**: Maps are now embedded directly in the `read` tool result text instead of being sent as separate `file-map` custom messages. This sacrifices the dedicated collapsible TUI widget but enables **true parallel tool execution**. Previously, custom messages interrupted parallel tool batches, causing skipped reads and forcing slow auto-recovery loops. Inlining guarantees the LLM receives the map immediately in the same turn, drastically speeding up parallel reads and preventing strict API conversation ordering errors (400 Bad Request).
+- Removed the `read-recovery` mechanism since parallel reads are no longer skipped by map generation.
+- Removed `@mariozechner/pi-tui` dependency since custom message rendering is no longer needed.
+
+### Fixed
+
+- Directory reads now throw an `EISDIR` error with inline `ls` fallback text reliably. The fallback listing is preserved in thrown errors instead of being swallowed by the internal `try/catch` path.
+- npm tarballs now exclude local scratch artifacts (`*.patch`, `*.orig`, `fix-*.js`, etc.) via `.npmignore`, preventing accidental publication of local debug/review files.
+
+## [1.2.5] - 2026-02-15
+
+### Fixed
+
+- `sendMessage` calls in `tool_result` handler now use `deliverAs: "followUp"` instead of the default `"steer"` mode. The default `"steer"` mode interrupts streaming and skips remaining parallel tools — when multiple reads ran concurrently and one triggered a file-map or directory-listing message, the remaining tool calls were skipped, leaving `tool_use` blocks without matching `tool_result` blocks. This caused a 400 error from the Claude API on the next request.
+
 ## [1.2.4] - 2026-02-15
 
 ### Fixed

package/README.md

@@ -160,13 +160,16 @@ The extension intercepts `read` calls and decides:
 1. **Binary files** (images, audio, video, archives, etc.): Delegate to built-in read tool
 2. **Small files** (≤2,000 lines, ≤50 KB): Delegate to built-in read tool
 3. **Targeted reads** (offset or limit provided): Delegate to built-in read tool
-4. **Large files:**
+4. **Directory paths**: Run built-in `ls` and throw an `EISDIR` error that includes inline fallback directory output.
+5. **Large files:**
    - Call built-in read for the first chunk
    - Detect language from file extension
    - Dispatch to a mapper (language-specific → ctags → grep fallback)
    - Format with budget enforcement
    - Cache the map
-   - Send as a separate `file-map` message after `tool_result`
+   - Append the map text directly to the read tool's result block
+
+*Note on design:* Maps are inlined as raw text rather than sent as separate custom UI messages. While this sacrifices a dedicated TUI widget, it ensures true parallel tool execution. Custom messages interrupt parallel tool batches, causing skipped reads and forcing slow recovery loops. Inlining guarantees the LLM receives the map immediately in the same turn without breaking concurrency.
 
 ## Dependencies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-read-map",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Pi extension that adds structural file maps for large files",
   "type": "module",
   "pi": {

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 import {
   createReadTool,
@@ -6,20 +6,15 @@ import {
   DEFAULT_MAX_LINES,
   DEFAULT_MAX_BYTES,
 } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { exec } from "node:child_process";
 import { stat } from "node:fs/promises";
-import { basename, extname, resolve } from "node:path";
+import { extname, resolve } from "node:path";
 import { promisify } from "node:util";
 
-import type { FileMapMessageDetails } from "./types.js";
-
 import { formatFileMapWithBudget } from "./formatter.js";
 import { generateMap, shouldGenerateMap } from "./mapper.js";
 
-export type { FileMapMessageDetails } from "./types.js";
-
 const execAsync = promisify(exec);
 
 /**
@@ -79,19 +74,6 @@ const BINARY_EXTENSIONS = new Set([
 // In-memory cache for maps
 const mapCache = new Map<string, { mtime: number; map: string }>();
 
-// Pending maps waiting to be sent after tool_result
-const pendingMaps = new Map<
-  string,
-  {
-    path: string;
-    map: string;
-    details: FileMapMessageDetails;
-  }
->();
-
-// Pending directory listings waiting to be sent after a read-on-directory error
-const pendingDirectoryLs = new Map<string, { path: string; listing: string }>();
-
 /**
  * Reset the map cache. Exported for testing purposes only.
  */
@@ -99,24 +81,6 @@ export function resetMapCache(): void {
   mapCache.clear();
 }
 
-/**
- * Reset the pending maps. Exported for testing purposes only.
- */
-export function resetPendingMaps(): void {
-  pendingMaps.clear();
-  pendingDirectoryLs.clear();
-}
-
-/**
- * Get pending maps for testing inspection.
- */
-export function getPendingMaps(): Map<
-  string,
-  { path: string; map: string; details: FileMapMessageDetails }
-> {
-  return pendingMaps;
-}
-
 export default function piReadMapExtension(pi: ExtensionAPI): void {
   // Get the current working directory
   const cwd = process.cwd();
@@ -127,160 +91,6 @@ export default function piReadMapExtension(pi: ExtensionAPI): void {
   // Create the built-in ls tool for directory fallback
   const builtInLs = createLsTool(cwd);
 
-  // Register tool_result handler to send pending maps and directory listings
-  pi.on("tool_result", (event, _ctx) => {
-    if (event.toolName !== "read") {
-      return;
-    }
-
-    // Send pending directory listing after read-on-directory error
-    const pendingLs = pendingDirectoryLs.get(event.toolCallId);
-    if (pendingLs) {
-      pi.sendMessage({
-        customType: "directory-listing",
-        content: `${pendingLs.path} is a directory. Here is ls:\n${pendingLs.listing}`,
-        display: true,
-      });
-      pendingDirectoryLs.delete(event.toolCallId);
-    }
-
-    const pending = pendingMaps.get(event.toolCallId);
-    if (!pending) {
-      return;
-    }
-
-    // Send the map as a custom message
-    pi.sendMessage({
-      customType: "file-map",
-      content: pending.map,
-      display: true,
-      details: pending.details,
-    });
-
-    // Clean up
-    pendingMaps.delete(event.toolCallId);
-  });
-
-  // Register custom message renderer for file-map type
-  pi.registerMessageRenderer<FileMapMessageDetails>(
-    "file-map",
-    (message, options, theme: Theme) => {
-      const { expanded } = options;
-      const { details } = message;
-
-      if (expanded) {
-        // Expanded: show full formatted map
-        // message.content can be string or array of content blocks
-        const content =
-          typeof message.content === "string"
-            ? message.content
-            : message.content
-                .filter((c) => c.type === "text")
-                .map((c) => (c as { type: "text"; text: string }).text)
-                .join("\n");
-        return new Text(content, 0, 0);
-      }
-
-      // Collapsed: show summary
-      const fileName = details ? basename(details.filePath) : "file";
-      const symbolCount = details?.symbolCount ?? 0;
-      const totalLines = details?.totalLines ?? 0;
-      const detailLanguage = details?.language ?? "unknown";
-
-      let summary = theme.fg("accent", "📄 File Map: ");
-      summary += theme.fg("toolTitle", theme.bold(fileName));
-      summary += theme.fg("muted", ` │ `);
-      summary += theme.fg("dim", `${symbolCount} symbols`);
-      summary += theme.fg("muted", ` │ `);
-      summary += theme.fg("dim", `${totalLines.toLocaleString()} lines`);
-      summary += theme.fg("muted", ` │ `);
-      summary += theme.fg("dim", detailLanguage);
-      summary += theme.fg("muted", ` │ `);
-      summary += theme.fg("dim", "Ctrl+O to expand");
-
-      return new Text(summary, 0, 0);
-    }
-  );
-
-  // Recover from skipped reads caused by map steering
-  pi.on("turn_end", (event) => {
-    const SKIPPED_TEXT = "Skipped due to queued user message.";
-
-    // Find skipped read results
-    const skippedReads = event.toolResults.filter(
-      (r) =>
-        r.toolName === "read" &&
-        !r.isError &&
-        r.content.some((c) => c.type === "text" && c.text === SKIPPED_TEXT)
-    );
-
-    if (skippedReads.length === 0) {
-      return;
-    }
-
-    // Extract paths from the assistant message's tool calls.
-    // The message is AgentMessage (union); narrow to AssistantMessage.
-    const msg = event.message;
-    if (!("role" in msg) || msg.role !== "assistant") {
-      return;
-    }
-
-    const skippedPaths: string[] = [];
-    for (const skipped of skippedReads) {
-      const tc = msg.content.find(
-        (c) =>
-          c.type === "toolCall" &&
-          c.name === "read" &&
-          c.id === skipped.toolCallId
-      );
-      if (tc && tc.type === "toolCall" && tc.arguments["path"]) {
-        skippedPaths.push(String(tc.arguments["path"]));
-      }
-    }
-
-    if (skippedPaths.length === 0) {
-      return;
-    }
-
-    const pathList = skippedPaths.map((p) => `- read("${p}")`).join("\n");
-
-    pi.sendMessage(
-      {
-        customType: "read-recovery",
-        content: `The following read() calls were interrupted by a file map delivery and need to be completed:\n${pathList}\nPlease re-issue these reads now.`,
-        display: true,
-      },
-      { deliverAs: "followUp" }
-    );
-  });
-
-  // Register custom message renderer for read-recovery type
-  pi.registerMessageRenderer(
-    "read-recovery",
-    (message, options, theme: Theme) => {
-      const content =
-        typeof message.content === "string"
-          ? message.content
-          : message.content
-              .filter((c) => c.type === "text")
-              .map((c) => (c as { type: "text"; text: string }).text)
-              .join("\n");
-
-      if (options.expanded) {
-        return new Text(content, 0, 0);
-      }
-
-      const pathCount = (content.match(/^- read\(/gm) || []).length;
-      let summary = theme.fg("warning", "Recovery: ");
-      summary += theme.fg(
-        "dim",
-        `${pathCount} interrupted read(s) being re-issued`
-      );
-
-      return new Text(summary, 0, 0);
-    }
-  );
-
   // Register our enhanced read tool
   pi.registerTool({
     name: "read",
@@ -328,27 +138,34 @@ export default function piReadMapExtension(pi: ExtensionAPI): void {
       // For non-regular files, handle appropriately
       if (!stats.isFile()) {
         if (stats.isDirectory()) {
-          // Get ls output before letting the error propagate
+          // Instead of letting EISDIR propagate and sending a custom steer message,
+          // we run ls and embed the listing directly into the thrown error.
+          // This prevents steer from breaking parallel executions.
+          let lsText: string | null = null;
           try {
             const lsResult = await builtInLs.execute(
               toolCallId,
               { path: inputPath },
               signal
             );
-            const lsText = lsResult.content
+            lsText = lsResult.content
               .filter(
                 (c): c is { type: "text"; text: string } => c.type === "text"
               )
               .map((c) => c.text)
               .join("\n");
-            pendingDirectoryLs.set(toolCallId, {
-              path: absPath,
-              listing: lsText,
-            });
           } catch {
             // best-effort: if ls fails, just let the error through without listing
           }
-          // Delegate to built-in read which will throw EISDIR
+
+          if (lsText !== null) {
+            // eslint-disable-next-line @factory/structured-logging
+            throw new Error(
+              `EISDIR: illegal operation on a directory, read '${absPath}'\n\nFallback ls output for this directory:\n${lsText}`
+            );
+          }
+
+          // Fallback if ls fails for some reason
           return builtInRead.execute(toolCallId, params, signal, onUpdate);
         }
         return builtInRead.execute(toolCallId, params, signal, onUpdate);
@@ -374,8 +191,7 @@ export default function piReadMapExtension(pi: ExtensionAPI): void {
         return builtInRead.execute(toolCallId, params, signal, onUpdate);
       }
 
-      // File exceeds threshold - generate map
-      // First, get the built-in result
+      // File exceeds threshold - generate map and inline it in the tool result
       const result = await builtInRead.execute(
         toolCallId,
         params,
@@ -383,57 +199,28 @@ export default function piReadMapExtension(pi: ExtensionAPI): void {
         onUpdate
       );
 
-      // Check cache
-      const cached = mapCache.get(absPath);
+      // Generate or retrieve cached map
       let mapText: string;
-      let symbolCount: number;
-      let language: string;
+      const cached = mapCache.get(absPath);
 
       if (cached && cached.mtime === stats.mtimeMs) {
-        // Cache hit - we need to regenerate map for metadata
-        // (alternatively, cache could store metadata too)
-        const fileMap = await generateMap(absPath, { signal });
-        if (fileMap) {
-          mapText = cached.map;
-          ({ language } = fileMap);
-          symbolCount = fileMap.symbols.length;
-        } else {
-          return result;
-        }
+        mapText = cached.map;
       } else {
-        // Generate new map
         const fileMap = await generateMap(absPath, { signal });
 
-        if (fileMap) {
-          mapText = formatFileMapWithBudget(fileMap);
-          ({ language } = fileMap);
-          symbolCount = fileMap.symbols.length;
-          // Cache it
-          mapCache.set(absPath, { mtime: stats.mtimeMs, map: mapText });
-        } else {
+        if (!fileMap) {
           // Map generation failed, return original result
           return result;
         }
-      }
 
-      // Store map in pendingMaps for delivery after tool_result event
-      pendingMaps.set(toolCallId, {
-        path: absPath,
-        map: mapText,
-        details: {
-          filePath: absPath,
-          totalLines,
-          totalBytes: stats.size,
-          symbolCount,
-          language,
-        },
-      });
+        mapText = formatFileMapWithBudget(fileMap);
+        mapCache.set(absPath, { mtime: stats.mtimeMs, map: mapText });
+      }
 
-      // Return the built-in result unmodified (with cleared truncation details
-      // since we're providing a map separately)
+      // Append map to the tool result content
       return {
         ...result,
-        details: undefined,
+        content: [...result.content, { type: "text" as const, text: mapText }],
       };
     },
   });

package/src/types.ts

@@ -81,15 +81,3 @@ export interface LanguageInfo {
 /**
  * Details for file map custom messages.
  */
-export interface FileMapMessageDetails {
-  /** Absolute file path */
-  filePath: string;
-  /** Total lines in file */
-  totalLines: number;
-  /** Total bytes in file */
-  totalBytes: number;
-  /** Number of symbols in map */
-  symbolCount: number;
-  /** Detected language */
-  language: string;
-}