pi-readseek 0.11.0 → 0.11.1

package/README.md

@@ -27,6 +27,11 @@ attachments without a separate extraction call. Reading never runs local inferen
 captioning, detection, and OCR require their explicit tools. Legacy tool names and
 selectable inspection facets are removed.
 
+The four `show` tools display readable summaries and grouped details rather than
+JSON dumps. Expand with Ctrl+O to reveal content; long lines wrap on resize.
+Source anchors, selected document nodes, asset paths, and continuation notices
+remain visible. Native results are retained in tool-result details.
+
 ## Settings
 
 Add `readseek` to `~/.pi/agent/settings.json` or `.pi/settings.json`:

package/dist/index.ts

@@ -1246,6 +1246,221 @@ function createReadSeekClient(runner) {
     }
   };
 }
+// ../readseek-api/src/show-presentation.ts
+function isShowTool(name) {
+  return name === "show_content" || name === "show_structure" || name === "show_metadata" || name === "show_assets";
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function records(value) {
+  return Array.isArray(value) ? value.map(record) : [];
+}
+function text(value) {
+  return typeof value === "string" ? value : "";
+}
+function count(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function safe(value) {
+  return value.replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, (char) => {
+    if (char === "\t")
+      return "\\t";
+    if (char === "\r")
+      return "\\r";
+    return `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+function inline(value) {
+  return safe(text(value)).replaceAll(`
+`, "\\n");
+}
+function plural(n, unit) {
+  return `${n} ${unit}${n === 1 ? "" : "s"}`;
+}
+function fields(value, omit = []) {
+  return Object.entries(value).flatMap(([key, item]) => {
+    if (omit.includes(key) || item === undefined || item === null || typeof item === "object")
+      return [];
+    const label = key.replaceAll("_", " ");
+    return [`${label[0]?.toUpperCase() ?? ""}${label.slice(1)}: ${safe(String(item))}`];
+  }).join(`
+`);
+}
+function location(value) {
+  const start = text(value.start_anchor) || (count(value.start_line) !== undefined ? `${value.start_line}${text(value.start_hash) ? `:${value.start_hash}` : ""}` : "");
+  const end = text(value.end_anchor) || (count(value.end_line) !== undefined ? `${value.end_line}${text(value.end_hash) ? `:${value.end_hash}` : ""}` : "");
+  return start ? `  ${inline(start)}${end && end !== start ? ` - ${inline(end)}` : ""}` : "";
+}
+function sourceStructure(structure) {
+  const sections = [];
+  if (structure.root) {
+    const lines = [];
+    const stack = [{ node: record(structure.root), depth: 0 }];
+    while (stack.length > 0) {
+      const { node, depth } = stack.pop();
+      lines.push(`${"  ".repeat(Math.min(depth, 12))}${inline(node.kind) || "node"}${text(node.name) ? ` ${inline(node.name)}` : ""}${location(node)}`);
+      const children = records(node.children);
+      for (let i = children.length - 1;i >= 0; i--)
+        stack.push({ node: children[i], depth: depth + 1 });
+    }
+    sections.push(`Tree
+${lines.join(`
+`)}`);
+  }
+  const symbols = records(structure.symbols);
+  if (symbols.length > 0) {
+    sections.push(`Symbols
+${symbols.map((symbol) => `${inline(symbol.kind) || "symbol"} ${inline(symbol.qualified_name || symbol.name)}${location(symbol)}`).join(`
+`)}`);
+  }
+  return sections.join(`
+
+`) || "No structure found in this selection.";
+}
+function documentNodes(nodes, content) {
+  const depths = new Map;
+  return nodes.map((node) => {
+    const depth = Math.min((depths.get(text(node.parent_id)) ?? -1) + 1, 12);
+    depths.set(text(node.id), depth);
+    const indent = "  ".repeat(depth);
+    const label = inline(node.title) || inline(node.kind) || "node";
+    const page = count(node.page);
+    const selector = text(node.id) ? `node:${inline(node.id)}` : "";
+    const position = [selector, page !== undefined ? `page:${page}` : ""].filter(Boolean).join(" · ");
+    const heading = `${indent}${label}${position ? `  [${position}]` : ""}`;
+    const body = text(node.text);
+    return content && body ? `${heading}
+${safe(body).split(`
+`).map((line) => indent + line).join(`
+`)}` : heading;
+  }).join(content ? `
+
+` : `
+`);
+}
+function assetList(assets) {
+  return assets.map((asset) => {
+    const id = text(asset.id);
+    const page = count(asset.page);
+    const heading = [id ? `asset:${inline(id)}` : inline(asset.kind) || "image", inline(asset.mime), page !== undefined ? `page:${page}` : ""].filter(Boolean).join(" · ");
+    const details = fields(asset, ["id", "kind", "mime", "page", "bbox", "content_identity"]);
+    return `${heading}${details ? `
+${details.split(`
+`).map((line) => `  ${line}`).join(`
+`)}` : ""}`;
+  }).join(`
+
+`);
+}
+function presentShowResult(tool, value, options = {}) {
+  const output = record(value);
+  const metadata = record(output.metadata);
+  const content = record(output.content);
+  const cursor = record(output.cursor);
+  const structure = record(output.structure);
+  const document = typeof output.format === "string" && (Array.isArray(output.nodes) || typeof output.source === "string");
+  const path = inline(options.path || output.source || output.file || content.file || structure.file || metadata.file || cursor.file) || "(unknown path)";
+  const summary = [];
+  const result = { summary: "", body: "", notices: [], metadata: {} };
+  if (tool === "show_metadata") {
+    const data = Object.keys(metadata).length > 0 ? metadata : output;
+    if (text(data.format || data.language || data.type))
+      summary.push(inline(data.format || data.language || data.type));
+    if (count(data.pages) !== undefined) {
+      result.metadata.pages = data.pages;
+      summary.push(plural(result.metadata.pages, "page"));
+    }
+    result.body = fields(data) || "No metadata available.";
+  } else if (tool === "show_assets") {
+    const assets = records(output.assets);
+    result.metadata.assets = assets.length;
+    summary.push(plural(assets.length, "asset"));
+    result.body = assetList(assets) || "No assets in this selection.";
+  } else if (document) {
+    const nodes = records(output.nodes);
+    const assets = records(output.assets);
+    result.metadata.nodes = nodes.length;
+    if (count(output.pages) !== undefined)
+      result.metadata.pages = output.pages;
+    summary.push(plural(nodes.length, "node"));
+    if (result.metadata.pages !== undefined)
+      summary.push(plural(result.metadata.pages, "page"));
+    const sections = [text(output.title) ? safe(text(output.title)) : "", documentNodes(nodes, tool === "show_content")];
+    if (assets.length > 0) {
+      result.metadata.assets = assets.length;
+      sections.push(`Assets
+${assetList(assets)}`);
+    }
+    result.body = sections.filter(Boolean).join(`
+
+`) || "No content in this selection.";
+  } else if (tool === "show_structure") {
+    const symbols = records(structure.symbols);
+    result.metadata.symbols = symbols.length;
+    summary.push(plural(symbols.length, "symbol"));
+    result.body = sourceStructure(structure);
+  } else if (content.kind === "image" || count(content.width) !== undefined && count(content.height) !== undefined || count(metadata.width) !== undefined && count(metadata.height) !== undefined || text(content.mime).startsWith("image/") || text(metadata.mime).startsWith("image/") || text(metadata.type).startsWith("image/")) {
+    const description = Object.keys(content).length > 0 ? content : Object.keys(metadata).length > 0 ? metadata : output;
+    if (count(description.width) !== undefined && count(description.height) !== undefined) {
+      summary.push(`${description.width} × ${description.height}`);
+    } else if (count(metadata.width) !== undefined && count(metadata.height) !== undefined) {
+      summary.push(`${metadata.width} × ${metadata.height}`);
+    }
+    const mime = text(description.mime || metadata.mime || metadata.type);
+    if (mime)
+      summary.push(inline(mime));
+    result.body = fields(description, ["hashlines"]) || fields(metadata) || "No content in this selection.";
+  } else if (Array.isArray(content.hashlines) || Array.isArray(cursor.hashlines)) {
+    const lines = records(content.hashlines ?? cursor.hashlines);
+    const start = count(content.start_line) ?? count(lines[0]?.line);
+    const end = count(content.end_line) ?? count(lines.at(-1)?.line);
+    const total = count(content.line_count) ?? count(cursor.line_count);
+    if (start !== undefined && end !== undefined && start <= end) {
+      result.metadata.start_line = start;
+      result.metadata.end_line = end;
+      summary.push(`lines ${start}-${end}${total !== undefined ? ` of ${total}` : ""}`);
+    } else
+      summary.push(plural(lines.length, "line"));
+    const lang = text(metadata.language || content.language);
+    if (lang)
+      summary.push(inline(lang));
+    const rows = lines.map((line) => `${line.line}${options.noAnchors ? "" : `:${text(line.hash)}`} | ${safe(text(line.text)).replaceAll("\\n", "\\\\n")}`);
+    const identifier = record(cursor.identifier);
+    if (count(cursor.line) !== undefined)
+      result.metadata.line = cursor.line;
+    if (count(cursor.column) !== undefined)
+      result.metadata.column = cursor.column;
+    if (Object.keys(cursor).length > 0) {
+      const symbol = record(cursor.symbol);
+      const description = [text(identifier.text), text(symbol.qualified_name || symbol.name), text(symbol.kind)].filter(Boolean);
+      rows.unshift(`Cursor: ${cursor.line ?? "?"}:${cursor.column ?? "?"}${description.length > 0 ? ` · ${[...new Set(description)].map(inline).join(" · ")}` : ""}`, "");
+    }
+    result.body = rows.join(`
+`) || "Empty source selection.";
+    if (start !== undefined && start > 1)
+      result.notices.push(`Earlier lines omitted. Read preceding content with at: line:1 and limit: ${start - 1}.`);
+    if (end !== undefined && total !== undefined && end < total) {
+      result.notices.push(`More lines available. Continue with at: line:${end + 1}.`);
+    } else if (content.truncated === true && (end === undefined || total === undefined)) {
+      result.notices.push(`Content is truncated.${end !== undefined ? ` Continue with at: line:${end + 1}.` : " Select a smaller range with at and limit."}`);
+    }
+  } else {
+    const description = Object.keys(content).length > 0 ? content : output;
+    result.body = fields(description) || "No content in this selection.";
+  }
+  if (tool === "show_structure")
+    result.notices.push("Structure is limited to the requested depth, kind, and outline. Use a deeper depth or focus with at to inspect further.");
+  if (text(output.warning))
+    result.notices.push(safe(text(output.warning)));
+  result.summary = summary.join(" · ") || "complete";
+  return result;
+}
+function formatShowResult(presentation) {
+  return [presentation.summary, presentation.body, ...presentation.notices.map((notice) => `Note: ${notice}`)].filter(Boolean).join(`
+
+`);
+}
 // ../readseek-api/src/platform.ts
 import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -3549,7 +3764,7 @@ function registerEditTool(pi, options = {}) {
       const cwd = context.cwd ?? process.cwd();
       const argsComplete = context.argsComplete ?? false;
       const { path: filePath, suffix } = formatEditCallText(args, argsComplete);
-      let text = theme.fg("toolTitle", theme.bold("edit"));
+      let text = theme.fg("toolTitle", theme.bold(name));
       if (filePath)
         text += ` ${linkToolPath(theme.fg("accent", filePath), filePath, cwd)}`;
       else
@@ -3566,7 +3781,7 @@ function registerEditTool(pi, options = {}) {
     renderResult(result, options, theme, ...rest) {
       const { isPartial, isError, expanded, width, context } = resolveRenderResultContext(options, rest, resolveReadSeekToolDisplayMode("edit") === "expanded");
       if (isPartial) {
-        return renderPendingResult("pending edit", width, theme);
+        return renderPendingResult(`pending ${name}`, width, theme);
       }
       const textContent = result.content?.filter((c) => c.type === "text").map((c) => c.text || "").join(`
 `) ?? "";
@@ -4421,7 +4636,7 @@ function registerGrepTool(pi, options = {}) {
       const { pattern, suffix } = formatGrepCallText(args);
       const rawPath = typeof args?.path === "string" && args.path !== "." ? args.path : undefined;
       const glob = typeof args?.glob === "string" ? args.glob : undefined;
-      let text = `${renderToolLabel(theme, "grep")} ${theme.fg("accent", `/${pattern}/`)}`;
+      let text = `${renderToolLabel(theme, name)} ${theme.fg("accent", `/${pattern}/`)}`;
       if (suffix) {
         if (rawPath) {
           text += theme.fg("dim", " in ");
@@ -4437,7 +4652,7 @@ function registerGrepTool(pi, options = {}) {
     renderResult(result, options, theme, ...rest) {
       const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest, resolveReadSeekToolDisplayMode("grep") === "expanded");
       if (isPartial)
-        return renderPendingResult("pending grep", width, theme);
+        return renderPendingResult(`pending ${name}`, width, theme);
       const content = result.content?.[0];
       const textContent = content?.type === "text" ? content.text : "";
       if (isError || result.isError)
@@ -4664,14 +4879,14 @@ function registerSearchTool(pi, options = {}) {
     },
     renderCall(args, theme, ...rest) {
       return renderReadSeekSearchCall(args, theme, rest, {
-        label: "search",
+        label: "readSeek_find_nodes",
         accent: `/${args.pattern ?? args.context ?? args.rule}/`,
         flags: [args.gitScope && `git-scope=${args.gitScope}`]
       });
     },
     renderResult(result, options, theme, ...rest) {
       return renderAnchoredFilesResult(result, options, theme, rest, {
-        pendingLabel: "pending search",
+        pendingLabel: "pending readSeek_find_nodes",
         emptyLabel: "no matches",
         unitSingular: "match",
         unitPlural: "matches"
@@ -4804,14 +5019,14 @@ function registerRefsTool(pi, options = {}) {
     renderCall(args, theme, ...rest) {
       const accent = args.name ?? args.at ?? "?";
       return renderReadSeekSearchCall(args, theme, rest, {
-        label: "refs",
+        label: "readSeek_find_references",
         accent,
         flags: [args.at && "binding", args.gitScope && `git-scope=${args.gitScope}`]
       });
     },
     renderResult(result, options, theme, ...rest) {
       return renderAnchoredFilesResult(result, options, theme, rest, {
-        pendingLabel: "pending refs",
+        pendingLabel: "pending readSeek_find_references",
         emptyLabel: "no references",
         unitSingular: "reference",
         unitPlural: "references"
@@ -4917,7 +5132,7 @@ function registerRenameTool(pi, options = {}) {
       const context = rest[0] ?? {};
       const cwd = context.cwd ?? process.cwd();
       const displayPath = typeof args?.path === "string" ? args.path : "?";
-      let text = theme.fg("toolTitle", theme.bold("rename"));
+      let text = theme.fg("toolTitle", theme.bold("readSeek_rename_symbol"));
       text += ` ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
       if (args?.to)
         text += theme.fg("dim", ` → ${args.to}`);
@@ -4926,13 +5141,13 @@ function registerRenameTool(pi, options = {}) {
     renderResult(result, options, theme, ...rest) {
       const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
       if (isPartial)
-        return renderPendingResult("pending rename", width, theme);
+        return renderPendingResult("pending readSeek_rename_symbol", width, theme);
       const content = result.content?.[0];
       const textContent = content?.type === "text" ? content.text : "";
       const readSeekValue = result.details?.readSeekValue;
       const output = readSeekValue?.output;
       if (isError || result.isError) {
-        return renderErrorResult(textContent, { expanded, width, fallback: "rename failed", theme });
+        return renderErrorResult(textContent, { expanded, width, fallback: "readSeek_rename_symbol failed", theme });
       }
       const outputs = output ? [output, ...output.others] : [];
       const editCount = outputs.reduce((total, file) => total + file.edits.length, 0);
@@ -5303,7 +5518,7 @@ function registerWriteTool(pi, options = {}) {
     renderCall(args, theme, context = {}) {
       const { path, content } = args;
       const cwd = context.cwd ?? process.cwd();
-      const label = renderToolLabel(theme, "write");
+      const label = renderToolLabel(theme, name);
       const lineCount = typeof content === "string" ? content.split(`
 `).length : 0;
       const bytes = typeof content === "string" ? Buffer.byteLength(content, "utf8") : 0;
@@ -5325,11 +5540,11 @@ function registerWriteTool(pi, options = {}) {
     renderResult(result, options, theme, ...rest) {
       const { isPartial, expanded, width, context } = resolveRenderResultContext(options, rest, resolveReadSeekToolDisplayMode("write") === "expanded");
       if (isPartial)
-        return renderPendingResult("pending write", width, theme);
+        return renderPendingResult(`pending ${name}`, width, theme);
       const details = result.details ?? {};
       const output = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (result.isError || details.readSeekValue?.ok === false) {
-        return renderErrorResult(output, { expanded, width, fallback: "write failed", theme });
+        return renderErrorResult(output, { expanded, width, fallback: `${name} failed`, theme });
       }
       const diffData = details.diffData;
       const state = details.writeState === "overwritten" ? "overwritten" : "created";
@@ -5444,14 +5659,14 @@ function registerDefTool(pi, options = {}) {
     },
     renderCall(args, theme, ...rest) {
       return renderReadSeekSearchCall(args, theme, rest, {
-        label: "def",
+        label: "readSeek_find_definitions",
         accent: args.name,
         flags: [args.gitScope && `git-scope=${args.gitScope}`]
       });
     },
     renderResult(result, options, theme, ...rest) {
       return renderAnchoredFilesResult(result, options, theme, rest, {
-        pendingLabel: "pending def",
+        pendingLabel: "pending readSeek_find_definitions",
         emptyLabel: "no definitions",
         unitSingular: "definition",
         unitPlural: "definitions"
@@ -5475,6 +5690,25 @@ var operations = {
   detect_objects: readSeekDetectObjects,
   recognize_text: readSeekRecognizeText
 };
+function resolveNonShowSummary(tool, envelope) {
+  if (tool === "check_syntax") {
+    const errorCount = envelope?.diagnostics?.error_count ?? 0;
+    return errorCount === 0 ? "clean" : `${errorCount} syntax error${errorCount === 1 ? "" : "s"}`;
+  }
+  if (tool === "check_rules") {
+    const violations = Array.isArray(envelope?.violations) ? envelope.violations.length : 0;
+    return violations === 0 ? "clean" : `${violations} rule violation${violations === 1 ? "" : "s"}`;
+  }
+  if (tool === "detect_objects") {
+    const objects = Array.isArray(envelope?.objects) ? envelope.objects.length : 0;
+    return `${objects} object${objects === 1 ? "" : "s"}`;
+  }
+  if (tool === "generate_caption")
+    return "caption generated";
+  if (tool === "recognize_text")
+    return "text recognized";
+  return "complete";
+}
 function hasAnchors(value) {
   if (!value || typeof value !== "object")
     return false;
@@ -5515,8 +5749,9 @@ async function executeAccess(opts) {
     const envelope = await operations[opts.tool](filePath, { ...options, signal: opts.signal });
     if (hasAnchors(envelope))
       opts.onFileAnchored?.(filePath);
+    const presentation = isShowTool(opts.tool) ? presentShowResult(opts.tool, envelope, p) : undefined;
     const content = [
-      { type: "text", text: JSON.stringify(envelope) }
+      { type: "text", text: presentation ? formatShowResult(presentation) : JSON.stringify(envelope) }
     ];
     if (opts.tool === "show_content" || opts.tool === "show_assets") {
       for (const [imagePath, mimeType] of imagePaths(envelope)) {
@@ -5528,7 +5763,7 @@ async function executeAccess(opts) {
           content.push({ type: "text", text: `Image available at ${imagePath}; this host model does not support image attachments.` });
       }
     }
-    return { content, details: { readSeekValue: { tool: opts.tool, ok: true, path: filePath, envelope } } };
+    return { content, details: { readSeekValue: { tool: opts.tool, ok: true, path: filePath, envelope, presentation } } };
   } catch (err) {
     const failure = classifyReadSeekFailure(err);
     return buildToolErrorResult(opts.tool, failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
@@ -5555,19 +5790,36 @@ function registerAccessTools(pi, options = {}) {
       async execute(_id, params, signal, _update, ctx) {
         return executeAccess({ tool: name, params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored, imageMode: options.imageMode, modelSupportsImages: ctx.model?.input.includes("image") ?? false });
       },
-      renderCall(args) {
-        return new Text7(`${name} ${args.path ?? ""}${args.at ? ` @ ${args.at}` : ""}`, 0, 0);
+      renderCall(args, theme, ...rest) {
+        const context = rest[0] ?? {};
+        const cwd = context.cwd ?? process.cwd();
+        const label = renderToolLabel(theme, registeredName);
+        const filePath = typeof args?.path === "string" ? args.path : args?.path ? String(args.path) : "";
+        const renderedPath = filePath ? linkToolPath(theme?.fg ? theme.fg("accent", filePath) : filePath, filePath, cwd) : "";
+        const atBadge = args?.at ? theme?.fg ? theme.fg("dim", ` @ ${args.at}`) : ` @ ${args.at}` : "";
+        const text = clampLineToWidth([label, renderedPath, atBadge].filter(Boolean).join(" "), context.width);
+        return upsertTextComponent(context.lastComponent, text);
       },
       renderResult(result, renderOptions, theme, ...rest) {
         const { isPartial, isError, expanded, width } = resolveRenderResultContext(renderOptions, rest);
         if (isPartial)
-          return renderPendingResult(`pending ${name}`, width, theme);
+          return renderPendingResult(`pending ${registeredName}`, width, theme);
         const text = result.content?.find((item) => item.type === "text")?.text ?? "";
         if (isError || result.isError)
-          return renderErrorResult(text, { expanded, width, fallback: `${name} failed`, theme });
-        const summary = summaryLine(contract.title, { hidden: !!text && !expanded, theme, style: "success" });
-        return new Text7(clampLinesToWidth((expanded ? `${summary}
-${text}` : summary).split(`
+          return renderErrorResult(text, { expanded, width, fallback: `${registeredName} failed`, theme });
+        const presentation = result.details?.readSeekValue?.presentation;
+        if (presentation) {
+          const summary = summaryLine(presentation.summary, { hidden: !!presentation.body && !expanded, theme, style: presentation.notices.length > 0 ? "warning" : "success" });
+          const notes = presentation.notices.map((notice) => `Note: ${notice}`);
+          const attachments = result.content?.filter((item) => item.type === "text").slice(1).map((item) => item.text) ?? [];
+          return new Text7([summary, ...expanded ? [presentation.body] : [], ...notes, ...attachments].filter(Boolean).join(`
+
+`), 0, 0);
+        }
+        const envelope = result.details?.readSeekValue?.envelope;
+        const nonShowSummary = resolveNonShowSummary(name, envelope);
+        const summary = summaryLine(nonShowSummary, { hidden: !!text && !expanded, theme, style: "success" });
+        return new Text7(clampLinesToWidth((expanded ? `${summary}\\n${text}` : summary).split(`
 `), width).join(`
 `), 0, 0);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
@@ -39,8 +39,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.11.0",
-    "@jarkkojs/readseek-api": "^0.11.0",
+    "@jarkkojs/readseek": "^0.11.1",
+    "@jarkkojs/readseek-api": "^0.11.1",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },