@alasano/pi-read-summary 0.0.1

package/README.md

@@ -0,0 +1,47 @@
+# pi-read-summary
+
+<p align="center">
+  <img src="assets/screenshot.png" alt="pi-read-summary screenshot" width="827" />
+</p>
+
+Compact grouped read summaries for [pi](https://pi.dev).
+
+`pi-read-summary` replaces large individual per-file `read` tool blocks with one local summary for each contiguous batch of reads. It keeps the model-facing read behavior unchanged while making the terminal easier to scan.
+
+## Install
+
+```bash
+pi install npm:@alasano/pi-read-summary
+```
+
+## Behavior
+
+- Overrides Pi's built-in `read` tool renderer while delegating execution to the built-in implementation.
+- Groups contiguous `read` calls into one compact summary block.
+- Shows relative paths for files inside the current working directory and absolute paths for files outside it.
+
+Collapsed output stays compact:
+
+```text
+● Read 3 files
+ └─ "AGENTS.md" [Read 54 lines]
+ └─ "package.json" [Read 42 lines]
+ └─ "packages/coding-agent/src/core/tools/read.ts" [Read 120 lines]
+```
+
+Expanded output (ctrl+o) uses Pi's shows merged line ranges:
+
+```text
+● Read 3 files
+ └─ "AGENTS.md" [Read 54 lines]
+     lines 1-54
+ └─ "package.json" [Read 42 lines]
+     lines 1-40, lines 60-61
+ └─ "packages/coding-agent/src/core/tools/read.ts" [Read 120 lines]
+     lines 1-120
+```
+
+## Requirements
+
+- Pi `0.79.9` or newer.
+- Node.js 22.19.0 or newer.

package/extensions/batches.ts

@@ -0,0 +1,49 @@
+import type { LineRange } from './ranges';
+
+export type ReadBatchEntry = {
+  path: string;
+  ranges: LineRange[];
+  inFlight: number;
+  isImage: boolean;
+  failed: boolean;
+};
+
+export type ReadBatch = {
+  id: string;
+  anchorToolCallId: string;
+  entries: ReadBatchEntry[];
+  inFlight: number;
+  pendingFinalize: boolean;
+  done: boolean;
+};
+
+export function getOrCreateEntry(batch: ReadBatch, path: string): ReadBatchEntry | undefined {
+  if (!path) return undefined;
+
+  const existing = batch.entries.find((entry) => entry.path === path);
+  if (existing) return existing;
+
+  const entry: ReadBatchEntry = {
+    path,
+    ranges: [],
+    inFlight: 0,
+    isImage: false,
+    failed: false,
+  };
+  batch.entries.push(entry);
+  return entry;
+}
+
+export function markEntryFailed(
+  batches: Map<string, ReadBatch>,
+  batchId: string,
+  path: string,
+): void {
+  const batch = batches.get(batchId);
+  if (!batch) return;
+
+  const entry = getOrCreateEntry(batch, path);
+  if (entry) {
+    entry.failed = true;
+  }
+}

package/extensions/index.ts

@@ -0,0 +1,243 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { Box } from '@earendil-works/pi-tui';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { createReadTool, isToolCallEventType } from '@earendil-works/pi-coding-agent';
+import { getOrCreateEntry, markEntryFailed, type ReadBatch } from './batches';
+import { normalizeDisplayPath } from './paths';
+import {
+  getReadStartLine,
+  extractReadLineCount,
+  isImageReadResult,
+  type ToolContentBlock,
+} from './read-result';
+import { addLineRange } from './ranges';
+import { createReadSummaryComponent } from './render';
+
+type RenderContextWithToolCallId = {
+  toolCallId: string;
+};
+
+type ReadSummaryMeta = {
+  __readSummary?: {
+    batchId: string;
+    toolCallId: string;
+  };
+};
+
+const batchesRef = new Map<string, ReadBatch>();
+
+function emptyComponent(): Component {
+  return { render: () => [], invalidate() {} };
+}
+
+function mergeDetailsWithMeta(
+  details: unknown,
+  meta: NonNullable<ReadSummaryMeta['__readSummary']>,
+): Record<string, unknown> {
+  if (details && typeof details === 'object' && !Array.isArray(details)) {
+    return {
+      ...(details as Record<string, unknown>),
+      __readSummary: meta,
+    };
+  }
+
+  return { __readSummary: meta };
+}
+
+function getSummaryMeta(details: unknown): ReadSummaryMeta['__readSummary'] | undefined {
+  if (!details || typeof details !== 'object' || Array.isArray(details)) return undefined;
+
+  const raw = (details as ReadSummaryMeta).__readSummary;
+  if (!raw) return undefined;
+  if (typeof raw.batchId !== 'string') return undefined;
+  if (typeof raw.toolCallId !== 'string') return undefined;
+  return raw;
+}
+
+export default function readSummaryExtension(pi: ExtensionAPI) {
+  const originalRead = createReadTool(process.cwd());
+  const batches = batchesRef;
+  const toolCallToBatch = new Map<string, string>();
+  const toolCallToPath = new Map<string, string>();
+
+  let activeBatchId: string | undefined;
+  let batchCounter = 0;
+
+  function clearState(): void {
+    batches.clear();
+    toolCallToBatch.clear();
+    toolCallToPath.clear();
+    activeBatchId = undefined;
+    batchCounter = 0;
+  }
+
+  function createBatch(anchorToolCallId: string): ReadBatch {
+    batchCounter += 1;
+    const batch: ReadBatch = {
+      id: `read-batch-${batchCounter}`,
+      anchorToolCallId,
+      entries: [],
+      inFlight: 0,
+      pendingFinalize: false,
+      done: false,
+    };
+
+    batches.set(batch.id, batch);
+    activeBatchId = batch.id;
+    return batch;
+  }
+
+  function startReadCall(toolCallId: string, path: string): ReadBatch {
+    let batch = activeBatchId ? batches.get(activeBatchId) : undefined;
+
+    if (!batch || batch.done || batch.pendingFinalize) {
+      batch = createBatch(toolCallId);
+    }
+
+    const entry = getOrCreateEntry(batch, path);
+    if (entry) {
+      entry.inFlight += 1;
+    }
+
+    batch.inFlight += 1;
+    toolCallToBatch.set(toolCallId, batch.id);
+    toolCallToPath.set(toolCallId, path);
+    return batch;
+  }
+
+  function markActiveBatchPendingFinalize(): void {
+    if (!activeBatchId) return;
+
+    const batch = batches.get(activeBatchId);
+    if (!batch) {
+      activeBatchId = undefined;
+      return;
+    }
+
+    batch.pendingFinalize = true;
+    if (batch.inFlight === 0) {
+      batch.done = true;
+      activeBatchId = undefined;
+    }
+  }
+
+  function completeReadCall(toolCallId: string): void {
+    const batchId = toolCallToBatch.get(toolCallId);
+    if (!batchId) return;
+
+    const batch = batches.get(batchId);
+    if (!batch) return;
+
+    batch.inFlight = Math.max(0, batch.inFlight - 1);
+
+    const path = toolCallToPath.get(toolCallId);
+    if (path) {
+      const entry = getOrCreateEntry(batch, path);
+      if (entry) {
+        entry.inFlight = Math.max(0, entry.inFlight - 1);
+      }
+    }
+
+    if (batch.pendingFinalize && batch.inFlight === 0) {
+      batch.done = true;
+      if (activeBatchId === batch.id) {
+        activeBatchId = undefined;
+      }
+    }
+  }
+
+  pi.on('tool_call', async (event) => {
+    if (isToolCallEventType('read', event)) {
+      startReadCall(event.toolCallId, normalizeDisplayPath(event.input.path));
+      return;
+    }
+
+    markActiveBatchPendingFinalize();
+  });
+
+  pi.on('message_end', async (event) => {
+    if (event.message.role === 'assistant' && event.message.stopReason !== 'toolUse') {
+      markActiveBatchPendingFinalize();
+    }
+  });
+
+  pi.on('agent_end', async () => {
+    markActiveBatchPendingFinalize();
+  });
+
+  pi.on('session_start', async () => {
+    clearState();
+  });
+
+  pi.registerTool({
+    name: 'read',
+    label: originalRead.label,
+    description: originalRead.description,
+    parameters: originalRead.parameters,
+    renderShell: 'self',
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const path = normalizeDisplayPath(params.path, ctx.cwd);
+      let batchId = toolCallToBatch.get(toolCallId);
+      if (!batchId) {
+        batchId = startReadCall(toolCallId, path).id;
+      }
+
+      try {
+        const result = await originalRead.execute(toolCallId, params, signal, onUpdate);
+
+        const batch = batches.get(batchId);
+        const entry = batch ? getOrCreateEntry(batch, path) : undefined;
+        if (entry) {
+          const resultLike = {
+            content: result.content as ToolContentBlock[] | undefined,
+            details: result.details,
+          };
+          entry.isImage = entry.isImage || isImageReadResult(resultLike);
+
+          if (!entry.isImage) {
+            const lineCount = extractReadLineCount(resultLike);
+            if (typeof lineCount === 'number') {
+              entry.ranges = addLineRange(entry.ranges, getReadStartLine(params), lineCount);
+            }
+          }
+        }
+
+        return {
+          ...result,
+          details: mergeDetailsWithMeta(result.details, { batchId, toolCallId }),
+        };
+      } catch (error) {
+        markEntryFailed(batches, batchId, path);
+        throw error;
+      } finally {
+        completeReadCall(toolCallId);
+      }
+    },
+
+    renderCall() {
+      return emptyComponent();
+    },
+
+    renderResult(result, options, theme, context: RenderContextWithToolCallId) {
+      let meta = getSummaryMeta(result.details);
+      if (!meta) {
+        const batchId = toolCallToBatch.get(context.toolCallId);
+        if (batchId) {
+          meta = { batchId, toolCallId: context.toolCallId };
+        }
+      }
+
+      if (!meta) return emptyComponent();
+
+      const batch = batches.get(meta.batchId);
+      if (!batch || batch.anchorToolCallId !== meta.toolCallId) {
+        return emptyComponent();
+      }
+
+      const box = new Box(1, 0);
+      box.addChild(createReadSummaryComponent(meta.batchId, batches, theme, options.expanded));
+      return box;
+    },
+  });
+}

package/extensions/paths.ts

@@ -0,0 +1,121 @@
+import * as nodePath from 'node:path';
+
+type ThemeColorKey = 'accent' | 'dim' | 'muted' | 'success' | 'syntaxString' | 'text' | 'warning';
+
+export type ThemeLike = {
+  fg: (color: ThemeColorKey, text: string) => string;
+};
+
+const DIR_GRADIENT_HEX = [
+  '#7f849c',
+  '#878ca2',
+  '#8f93a8',
+  '#979baf',
+  '#9fa3b5',
+  '#a7aabb',
+  '#afb2c1',
+  '#b7bac7',
+  '#bfc2ce',
+  '#c7c9d4',
+  '#cfd1da',
+  '#d7d9e0',
+  '#dfe0e6',
+] as const;
+
+const FILE_COLOR = 'syntaxString';
+const rgbCache = new Map<string, { r: number; g: number; b: number }>();
+
+function isWithinDirectory(absolutePath: string, cwd: string): boolean {
+  const relativePath = nodePath.relative(cwd, absolutePath);
+  return (
+    relativePath === '' || (!relativePath.startsWith('..') && !nodePath.isAbsolute(relativePath))
+  );
+}
+
+export function toDisplaySeparators(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+export function normalizeDisplayPath(inputPath: unknown, cwd: string = process.cwd()): string {
+  if (typeof inputPath !== 'string') return '(unknown path)';
+
+  const trimmed = inputPath.trim();
+  const stripped = trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+  if (!stripped) return '(unknown path)';
+
+  const absolutePath = nodePath.isAbsolute(stripped)
+    ? nodePath.normalize(stripped)
+    : nodePath.resolve(cwd, stripped);
+
+  if (isWithinDirectory(absolutePath, cwd)) {
+    const relativePath = nodePath.relative(cwd, absolutePath);
+    return toDisplaySeparators(relativePath || '.');
+  }
+
+  return toDisplaySeparators(absolutePath);
+}
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } | undefined {
+  const cached = rgbCache.get(hex);
+  if (cached) return cached;
+
+  const cleaned = hex.trim().replace('#', '');
+  if (!/^[0-9a-fA-F]{6}$/.test(cleaned)) return undefined;
+
+  const rgb = {
+    r: Number.parseInt(cleaned.slice(0, 2), 16),
+    g: Number.parseInt(cleaned.slice(2, 4), 16),
+    b: Number.parseInt(cleaned.slice(4, 6), 16),
+  };
+
+  rgbCache.set(hex, rgb);
+  return rgb;
+}
+
+function fgHex(hex: string, text: string): string {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return text;
+  return `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m${text}\x1b[39m`;
+}
+
+function getDirColorHex(depth: number, totalDirs: number): string {
+  if (totalDirs <= 1) return DIR_GRADIENT_HEX[0];
+
+  const t = depth / Math.max(1, totalDirs - 1);
+  const index = Math.round(t * (DIR_GRADIENT_HEX.length - 1));
+  return (
+    DIR_GRADIENT_HEX[Math.min(DIR_GRADIENT_HEX.length - 1, Math.max(0, index))] ??
+    DIR_GRADIENT_HEX[0]
+  );
+}
+
+export function stylePath(path: string, theme: ThemeLike): string {
+  const normalizedPath = toDisplaySeparators(path);
+  const hasLeadingSlash = normalizedPath.startsWith('/');
+  const segments = normalizedPath.split('/').filter((segment) => segment.length > 0);
+
+  if (segments.length === 0) {
+    return theme.fg(FILE_COLOR, normalizedPath || path);
+  }
+
+  if (segments.length === 1 && !hasLeadingSlash) {
+    return theme.fg(FILE_COLOR, segments[0] ?? normalizedPath);
+  }
+
+  const directoryCount = Math.max(0, segments.length - 1);
+  let styled = '';
+
+  if (hasLeadingSlash) {
+    styled += fgHex(getDirColorHex(0, Math.max(1, directoryCount)), '/');
+  }
+
+  for (let index = 0; index < directoryCount; index += 1) {
+    const segment = segments[index];
+    if (segment) {
+      styled += fgHex(getDirColorHex(index, directoryCount), `${segment}/`);
+    }
+  }
+
+  styled += theme.fg(FILE_COLOR, segments[segments.length - 1] ?? normalizedPath);
+  return styled;
+}

package/extensions/ranges.ts

@@ -0,0 +1,47 @@
+export type LineRange = {
+  start: number;
+  end: number;
+};
+
+export function positiveInteger(value: unknown): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+
+  const integer = Math.floor(value);
+  return integer > 0 ? integer : undefined;
+}
+
+export function mergeRanges(ranges: LineRange[]): LineRange[] {
+  const sorted = ranges
+    .filter((range) => range.start > 0 && range.end >= range.start)
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+
+  const merged: LineRange[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (!last || range.start > last.end + 1) {
+      merged.push({ ...range });
+    } else {
+      last.end = Math.max(last.end, range.end);
+    }
+  }
+
+  return merged;
+}
+
+export function addLineRange(ranges: LineRange[], start: number, lineCount: number): LineRange[] {
+  if (lineCount <= 0) return ranges;
+
+  return mergeRanges([...ranges, { start, end: start + lineCount - 1 }]);
+}
+
+export function countRangeLines(ranges: LineRange[]): number {
+  return ranges.reduce((sum, range) => sum + range.end - range.start + 1, 0);
+}
+
+function formatLineRange(range: LineRange): string {
+  return range.start === range.end ? `line ${range.start}` : `lines ${range.start}-${range.end}`;
+}
+
+export function formatLineRanges(ranges: LineRange[]): string {
+  return ranges.map(formatLineRange).join(', ');
+}

package/extensions/read-result.ts

@@ -0,0 +1,68 @@
+import { positiveInteger } from './ranges';
+
+export type ToolContentBlock = {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+};
+
+export type ReadResultLike = {
+  content?: ToolContentBlock[];
+  details?: unknown;
+};
+
+export function getReadStartLine(args: unknown): number {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return 1;
+  return positiveInteger((args as { offset?: unknown }).offset) ?? 1;
+}
+
+export function isImageReadResult(result: ReadResultLike): boolean {
+  return result.content?.some((block) => block.type === 'image') === true;
+}
+
+function findTextContent(content: ToolContentBlock[] | undefined): string | undefined {
+  if (!content) return undefined;
+
+  const textBlock = content.find(
+    (block) => block.type === 'text' && typeof block.text === 'string',
+  );
+  return textBlock?.text;
+}
+
+function extractLineCountFromText(text: string): number {
+  const showingMatch = text.match(
+    /\[Showing lines (\d+)-(\d+) of \d+(?: \([^)]+\))?\. Use offset=\d+ to continue\.\]\s*$/,
+  );
+  if (showingMatch) {
+    const start = Number.parseInt(showingMatch[1] ?? '', 10);
+    const end = Number.parseInt(showingMatch[2] ?? '', 10);
+    if (!Number.isNaN(start) && !Number.isNaN(end) && end >= start) {
+      return end - start + 1;
+    }
+  }
+
+  const textWithoutNotice = text
+    .replace(
+      /\n\n\[Showing lines \d+-\d+ of \d+(?: \([^)]+\))?\. Use offset=\d+ to continue\.\]\s*$/,
+      '',
+    )
+    .replace(/\n\n\[\d+ more lines in file\. Use offset=\d+ to continue\.\]\s*$/, '');
+
+  if (!textWithoutNotice) return 0;
+  return textWithoutNotice.split('\n').length;
+}
+
+export function extractReadLineCount(result: ReadResultLike): number | undefined {
+  if (result.details && typeof result.details === 'object' && !Array.isArray(result.details)) {
+    const truncation = (result.details as { truncation?: { outputLines?: unknown } }).truncation;
+    if (truncation && typeof truncation.outputLines === 'number') {
+      return truncation.outputLines;
+    }
+  }
+
+  const text = findTextContent(result.content);
+  if (typeof text !== 'string') return undefined;
+
+  return extractLineCountFromText(text);
+}

package/extensions/render.ts

@@ -0,0 +1,94 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import type { ReadBatch, ReadBatchEntry } from './batches';
+import { stylePath, type ThemeLike } from './paths';
+import { countRangeLines, formatLineRanges } from './ranges';
+
+function pluralizeFiles(count: number): string {
+  return `${count} file${count === 1 ? '' : 's'}`;
+}
+
+function pluralizeLines(count: number): string {
+  return `${count} line${count === 1 ? '' : 's'}`;
+}
+
+function getEntryStatus(entry: ReadBatchEntry, theme: ThemeLike): string {
+  if (entry.failed) {
+    return `${theme.fg('dim', '[')}${theme.fg('warning', 'Read failed')}${theme.fg('dim', ']')}`;
+  }
+
+  if (entry.isImage) {
+    return `${theme.fg('dim', '[')}${theme.fg('muted', 'Read image')}${theme.fg('dim', ']')}`;
+  }
+
+  const uniqueLineCount = countRangeLines(entry.ranges);
+  if (uniqueLineCount > 0) {
+    return `${theme.fg('dim', '[')}${theme.fg('muted', `Read ${pluralizeLines(uniqueLineCount)}`)}${theme.fg('dim', ']')}`;
+  }
+
+  if (entry.inFlight > 0) {
+    return `${theme.fg('dim', '[')}${theme.fg('muted', 'Reading…')}${theme.fg('dim', ']')}`;
+  }
+
+  return `${theme.fg('dim', '[')}${theme.fg('muted', 'Read file')}${theme.fg('dim', ']')}`;
+}
+
+function formatEntryLine(entry: ReadBatchEntry, theme: ThemeLike, width: number): string {
+  const prefix = theme.fg('dim', '└─ "');
+  const path = stylePath(entry.path, theme);
+  const suffix = theme.fg('dim', '"');
+  const annotation = getEntryStatus(entry, theme);
+  const suffixAndAnnotation = `${suffix} ${annotation}`;
+  const pathWidth = width - visibleWidth(prefix) - visibleWidth(suffixAndAnnotation);
+
+  if (pathWidth <= 0) {
+    return truncateToWidth(`${prefix}${path}${suffixAndAnnotation}`, width);
+  }
+
+  return `${prefix}${truncateToWidth(path, pathWidth, '…')}${suffixAndAnnotation}`;
+}
+
+export function createReadSummaryComponent(
+  batchId: string,
+  batches: Map<string, ReadBatch>,
+  theme: ThemeLike,
+  expanded: boolean,
+): Component {
+  return {
+    render(width: number): string[] {
+      const batch = batches.get(batchId);
+      if (!batch) return [];
+
+      const safeWidth = Math.max(1, width);
+      const fileCount = batch.entries.length;
+      const failedCount = batch.entries.filter((entry) => entry.failed).length;
+      const statusDot = batch.done ? theme.fg('success', '●') : theme.fg('text', '○');
+      const statusText = batch.done
+        ? theme.fg('success', `Read ${pluralizeFiles(fileCount)}`)
+        : theme.fg('accent', `Reading ${pluralizeFiles(fileCount)}…`);
+
+      let firstLine = `${statusDot} ${statusText}`;
+      if (failedCount > 0) {
+        firstLine += ` ${theme.fg('warning', `(${failedCount} failed)`)}`;
+      }
+
+      const lines = [truncateToWidth(firstLine, safeWidth)];
+
+      for (const entry of batch.entries) {
+        lines.push(formatEntryLine(entry, theme, safeWidth));
+
+        if (expanded && entry.ranges.length > 0) {
+          lines.push(
+            truncateToWidth(
+              `${theme.fg('dim', '   ')} ${theme.fg('muted', formatLineRanges(entry.ranges))}`,
+              safeWidth,
+            ),
+          );
+        }
+      }
+
+      return lines;
+    },
+    invalidate() {},
+  };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@alasano/pi-read-summary",
+  "version": "0.0.1",
+  "description": "Compact grouped read summaries for pi",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasano/house-of-pi",
+    "directory": "packages/pi-read-summary"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "image": "https://raw.githubusercontent.com/alasano/house-of-pi/master/packages/pi-read-summary/assets/screenshot.png"
+  },
+  "files": [
+    "extensions",
+    "assets",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.79.9",
+    "@earendil-works/pi-tui": ">=0.79.9"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.79.9",
+    "@earendil-works/pi-tui": "^0.79.9"
+  }
+}