pi-diet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProbabilityEngineer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# pi-diet
+
+Compact oversized Pi tool results with transparent previews and spill files.
+
+`pi-diet` keeps Pi sessions lean by filtering runaway tool outputs before they bloat model context and session JSONL files. Small results pass through unchanged. Large results are saved losslessly under `~/.pi/agent/pi-diet/spills/` and replaced with a compact preview, tail, omitted-size count, and spill path.
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:pi-diet
+```
+
+From GitHub:
+
+```bash
+pi install git:github.com/ProbabilityEngineer/pi-diet
+```
+
+For local development without installing:
+
+```bash
+pi -e ./index.ts
+```
+
+## Status
+
+Early MVP, but validated against a real Pi session for oversized bash output.
+
+## Behavior
+
+- pass through small tool results unchanged
+- compact oversized tool results automatically via the Pi `tool_result` hook
+- spill full original output to disk before replacing model-visible content
+- preserve transparent access to the full output via a spill-file path
+- provide specialized previews for bash, read-image, noisy LSP JSON, and generic search-style output
+
+## Default thresholds
+
+- `thresholdChars`: 64000
+- `headChars`: 8000
+- `tailChars`: 8000
+
+## Commands
+
+- `/diet-pi status`
+- `/diet-pi on`
+- `/diet-pi off`
+
+## Example
+
+Ask Pi to run a command with very large output. Instead of storing the whole result in model context, `pi-diet` will replace it with a compact marker and a spill path like:
+
+```text
+[pi-diet: compacted oversized bash result]
+Original size: 102955 chars
+Full output: ~/.pi/agent/pi-diet/spills/...
+```
+
+## Rescue script
+
+Rescue a single session file:
+
+```bash
+node scripts/rescue-session.mjs ~/.pi/agent/sessions/.../session.jsonl --out /tmp/pi-diet-rescue
+```
+
+Rescue every session file under a directory:
+
+```bash
+node scripts/rescue-session.mjs ~/.pi/agent/sessions/some-project --out /tmp/pi-diet-rescue
+```
+
+## Development
+
+```bash
+npm test
+```
+
+## Safety
+
+`pi-diet` does not silently discard oversized tool results. It writes the full original result to a spill file first, then replaces the model-visible content with a compact preview.

package/index.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import { compactToolResult, DEFAULT_SETTINGS, type DietPiSettings, type ToolContentBlock } from "./src/diet.ts";
+
+const STATUS_KEY = "pi-diet";
+
+export default function dietPi(pi: ExtensionAPI) {
+  let settings: DietPiSettings = { ...DEFAULT_SETTINGS };
+
+  function statusText(): string {
+    return `pi-diet ${settings.enabled ? "on" : "off"} · threshold=${settings.thresholdChars} · head=${settings.headChars} · tail=${settings.tailChars}`;
+  }
+
+  function refreshStatus(ctx: { hasUI: boolean; ui: { setStatus: (key: string, text: string | undefined) => void } }) {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus(STATUS_KEY, statusText());
+  }
+
+  pi.registerCommand("diet-pi", {
+    description: "Control pi-diet result compaction: status | on | off",
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+      if (!action || action === "status") {
+        ctx.ui.notify(statusText(), "info");
+        refreshStatus(ctx);
+        return;
+      }
+      if (action === "on") {
+        settings = { ...settings, enabled: true };
+        ctx.ui.notify("pi-diet enabled", "info");
+        refreshStatus(ctx);
+        return;
+      }
+      if (action === "off") {
+        settings = { ...settings, enabled: false };
+        ctx.ui.notify("pi-diet disabled", "info");
+        refreshStatus(ctx);
+        return;
+      }
+      ctx.ui.notify("Usage: /diet-pi status|on|off", "warning");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    refreshStatus(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  });
+
+  pi.on("tool_result", async (event: ToolResultEvent) => {
+    const patch = await compactToolResult({
+      toolName: event.toolName,
+      toolCallId: event.toolCallId,
+      input: event.input,
+      content: event.content as ToolContentBlock[],
+      details: event.details,
+      isError: event.isError,
+      settings,
+    });
+    return patch ?? undefined;
+  });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pi-diet",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Compact oversized Pi tool results with transparent previews and spill files.",
+  "type": "module",
+  "license": "MIT",
+  "author": "ProbabilityEngineer",
+  "homepage": "https://github.com/ProbabilityEngineer/pi-diet#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProbabilityEngineer/pi-diet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ProbabilityEngineer/pi-diet/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "tool-results",
+    "context",
+    "sessions"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.76.0",
+    "typescript": "^5.9.3",
+    "typebox": "latest"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  }
+}

package/scripts/rescue-session.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { compactToolResult, DEFAULT_SETTINGS } from "../src/diet.ts";
+
+async function collectJsonlFiles(inputPath) {
+  const info = await stat(inputPath);
+  if (info.isFile()) return [inputPath];
+  if (!info.isDirectory()) return [];
+
+  const found = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const next = join(dir, entry.name);
+      if (entry.isDirectory()) await walk(next);
+      else if (entry.isFile() && entry.name.endsWith('.jsonl')) found.push(next);
+    }
+  }
+
+  await walk(inputPath);
+  return found.sort();
+}
+
+async function rescueFile(resolvedInput, outDir) {
+  const text = await readFile(resolvedInput, 'utf8');
+  const lines = text.split('\n');
+  let changed = 0;
+
+  const nextLines = await Promise.all(lines.map(async (line) => {
+    if (!line.trim()) return line;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return line;
+    }
+
+    const message = parsed?.message;
+    if (!message || message.role !== 'toolResult' || !Array.isArray(message.content)) {
+      return line;
+    }
+
+    const patch = await compactToolResult({
+      toolName: message.toolName ?? 'tool',
+      toolCallId: message.toolCallId ?? parsed.id ?? 'tool-call',
+      input: message.input ?? {},
+      content: message.content,
+      details: message.details,
+      isError: Boolean(message.isError),
+      settings: DEFAULT_SETTINGS,
+    });
+
+    if (!patch) return line;
+    changed += 1;
+    parsed.message = {
+      ...message,
+      content: patch.content,
+      details: patch.details,
+      isError: patch.isError ?? message.isError,
+    };
+    return JSON.stringify(parsed);
+  }));
+
+  await mkdir(outDir, { recursive: true });
+  const outPath = join(outDir, `${basename(resolvedInput, '.jsonl')}.rescued.jsonl`);
+  await writeFile(outPath, nextLines.join('\n'), 'utf8');
+  return { changed, outPath };
+}
+
+async function main() {
+  const [, , inputPath, ...args] = process.argv;
+  if (!inputPath) {
+    console.error('Usage: node scripts/rescue-session.mjs <session.jsonl|dir> [--out DIR]');
+    process.exit(1);
+  }
+
+  const outIndex = args.indexOf('--out');
+  const outRoot = outIndex >= 0 ? resolve(args[outIndex + 1]) : dirname(resolve(inputPath));
+  const resolvedInput = resolve(inputPath);
+  const files = await collectJsonlFiles(resolvedInput);
+  if (!files.length) {
+    console.error(`No .jsonl files found under ${resolvedInput}`);
+    process.exit(1);
+  }
+
+  let totalChanged = 0;
+  for (const file of files) {
+    const relativeDir = files.length === 1 ? '' : dirname(relative(resolvedInput, file));
+    const outDir = join(outRoot, relativeDir);
+    const result = await rescueFile(file, outDir);
+    totalChanged += result.changed;
+    console.log(`file=${file} rescued=${result.changed} output=${result.outPath}`);
+  }
+  console.log(`summary files=${files.length} rescued=${totalChanged} out=${outRoot}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/diet.ts

@@ -0,0 +1,325 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ToolContentBlock = {
+  type: string;
+  text?: string;
+  source?: { type?: string; mediaType?: string; data?: string };
+  [key: string]: unknown;
+};
+
+export type DietPiSettings = {
+  enabled: boolean;
+  thresholdChars: number;
+  headChars: number;
+  tailChars: number;
+  spillDir: string;
+};
+
+export type SpillRecord = {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+  isError: boolean;
+  content: unknown;
+  details: unknown;
+};
+
+export type CompactionPatch = {
+  content: ToolContentBlock[];
+  details: unknown;
+  isError?: boolean;
+};
+
+export type AnalyzeResult = {
+  text: string;
+  charCount: number;
+  kind: "bash" | "image-read" | "lsp-json" | "searchish" | "generic";
+  metadataLines: string[];
+  previewText?: string;
+};
+
+export const DEFAULT_SETTINGS: DietPiSettings = {
+  enabled: true,
+  thresholdChars: 64_000,
+  headChars: 8_000,
+  tailChars: 8_000,
+  spillDir: join(resolveAgentDir(), "pi-diet", "spills"),
+};
+
+export function resolveAgentDir(): string {
+  try {
+    return getAgentDir();
+  } catch {
+    return join(homedir(), ".pi", "agent");
+  }
+}
+
+export function sanitizeForFileName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
+export function timestampForFileName(date = new Date()): string {
+  return date.toISOString().replace(/[:]/g, "-").replace(/\.\d{3}Z$/, "Z");
+}
+
+export function renderContentBlocks(content: ToolContentBlock[]): string {
+  const lines: string[] = [];
+  for (const block of content) {
+    if (block.type === "text") {
+      lines.push(block.text ?? "");
+      continue;
+    }
+
+    if (block.type === "image") {
+      const mediaType = typeof block.source?.mediaType === "string" ? block.source.mediaType : "image/unknown";
+      const dataLength = typeof block.source?.data === "string" ? block.source.data.length : 0;
+      lines.push(`[image block ${mediaType}${dataLength ? ` data=${dataLength} chars` : ""}]`);
+      continue;
+    }
+
+    lines.push(`[${block.type} block] ${safeJson(block)}`);
+  }
+  return lines.join("\n");
+}
+
+export function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export function analyzeToolResult(toolName: string, content: ToolContentBlock[], details: unknown): AnalyzeResult {
+  const text = renderContentBlocks(content);
+  const detailsText = details === undefined ? "" : `\n\n--- details ---\n${safeJson(details)}`;
+  const fullText = `${text}${detailsText}`;
+
+  const lspPreview = looksLikeLspJson(fullText) ? extractLspSummary(fullText) : null;
+  if (lspPreview) {
+    return {
+      text: fullText,
+      charCount: fullText.length,
+      kind: "lsp-json",
+      metadataLines: [
+        `Approx locations/symbols: ${lspPreview.count}`,
+        ...(lspPreview.samples.length ? [`Sample locations: ${lspPreview.samples.join("; ")}`] : []),
+      ],
+      previewText: lspPreview.previewText,
+    };
+  }
+
+  if (toolName === "read" && hasImagePayload(content, text)) {
+    const imagePreview = extractImageSummary(content, fullText, details);
+    return {
+      text: fullText,
+      charCount: fullText.length,
+      kind: "image-read",
+      metadataLines: imagePreview.metadataLines,
+      previewText: imagePreview.previewText,
+    };
+  }
+
+  if (toolName === "bash") {
+    const bashPreview = extractBashSummary(fullText);
+    return {
+      text: fullText,
+      charCount: fullText.length,
+      kind: "bash",
+      metadataLines: bashPreview.metadataLines,
+      previewText: bashPreview.previewText,
+    };
+  }
+
+  if (toolName.includes("search") || toolName.includes("grep") || toolName.includes("references") || toolName.includes("symbols")) {
+    const searchPreview = extractSearchSummary(fullText);
+    return {
+      text: fullText,
+      charCount: fullText.length,
+      kind: "searchish",
+      metadataLines: searchPreview.metadataLines,
+      previewText: searchPreview.previewText,
+    };
+  }
+
+  return {
+    text: fullText,
+    charCount: fullText.length,
+    kind: "generic",
+    metadataLines: [],
+  };
+}
+
+export function buildPreview(analyze: AnalyzeResult, settings: DietPiSettings): string {
+  if (analyze.previewText) return analyze.previewText;
+
+  const head = analyze.text.slice(0, settings.headChars);
+  const tail = analyze.text.slice(-settings.tailChars);
+  if (analyze.text.length <= settings.headChars + settings.tailChars) return head;
+  return `--- head ---\n${head}\n\n--- tail ---\n${tail}`;
+}
+
+export function buildCompactedText(args: {
+  toolName: string;
+  toolCallId: string;
+  analyze: AnalyzeResult;
+  settings: DietPiSettings;
+  spillPath: string;
+}): string {
+  const { toolName, toolCallId, analyze, settings, spillPath } = args;
+  const omitted = Math.max(0, analyze.charCount - Math.min(analyze.charCount, settings.headChars + settings.tailChars));
+  const metadata = analyze.metadataLines.length ? `${analyze.metadataLines.join("\n")}\n` : "";
+  return [
+    `[pi-diet: compacted oversized ${toolName} result]`,
+    `Tool call: ${toolCallId}`,
+    `Recognizer: ${analyze.kind}`,
+    `Original size: ${analyze.charCount} chars`,
+    `Preview: first ${settings.headChars} chars + last ${settings.tailChars} chars shown unless specialized`,
+    `Omitted: ${omitted} chars`,
+    `Full output: ${spillPath}`,
+    metadata.trimEnd(),
+    buildPreview(analyze, settings),
+  ].filter(Boolean).join("\n\n");
+}
+
+export async function writeSpillFile(record: SpillRecord, settings: DietPiSettings): Promise<string> {
+  const fileName = `${timestampForFileName()}-${sanitizeForFileName(record.toolName)}-${sanitizeForFileName(record.toolCallId)}.txt`;
+  const spillPath = join(settings.spillDir, fileName);
+  await mkdir(dirname(spillPath), { recursive: true });
+  await writeFile(spillPath, safeJson(record), "utf8");
+  return spillPath;
+}
+
+export async function compactToolResult(args: {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+  content: ToolContentBlock[];
+  details: unknown;
+  isError: boolean;
+  settings: DietPiSettings;
+}): Promise<CompactionPatch | null> {
+  const { toolName, toolCallId, input, content, details, isError, settings } = args;
+  if (!settings.enabled) return null;
+
+  const analyzed = analyzeToolResult(toolName, content, details);
+  if (analyzed.charCount <= settings.thresholdChars) return null;
+
+  const spillPath = await writeSpillFile({ toolName, toolCallId, input, content, details, isError }, settings);
+  const compactedText = buildCompactedText({ toolName, toolCallId, analyze: analyzed, settings, spillPath });
+
+  return {
+    content: [{ type: "text", text: compactedText }],
+    details: mergeDietDetails(details, {
+      compacted: true,
+      spillPath,
+      originalSizeChars: analyzed.charCount,
+      thresholdChars: settings.thresholdChars,
+      recognizer: analyzed.kind,
+    }),
+    isError,
+  };
+}
+
+export function mergeDietDetails(details: unknown, dietPi: Record<string, unknown>): unknown {
+  if (details && typeof details === "object" && !Array.isArray(details)) {
+    return { ...(details as Record<string, unknown>), dietPi };
+  }
+  return { originalDetails: details ?? null, dietPi };
+}
+
+export function countOccurrences(text: string, needle: string): number {
+  if (!needle) return 0;
+  let count = 0;
+  let index = 0;
+  while (true) {
+    index = text.indexOf(needle, index);
+    if (index === -1) return count;
+    count += 1;
+    index += needle.length;
+  }
+}
+
+export function looksLikeLspJson(text: string): boolean {
+  return countOccurrences(text, '"uri"') >= 3 && countOccurrences(text, '"range"') >= 3 && countOccurrences(text, '"line"') >= 3;
+}
+
+export function hasImagePayload(content: ToolContentBlock[], text: string): boolean {
+  if (content.some((block) => block.type === "image")) return true;
+  return /image\/(png|jpeg|jpg|gif|webp)/i.test(text) || /read image file/i.test(text);
+}
+
+export function extractLspSummary(text: string): { count: number; samples: string[]; previewText: string } | null {
+  const matches = Array.from(text.matchAll(/"uri"\s*:\s*"file:\/\/([^"\n]+)"[\s\S]{0,160}?"line"\s*:\s*(\d+)[\s\S]{0,80}?"character"\s*:\s*(\d+)/g));
+  if (!matches.length) return null;
+  const samples = matches.slice(0, 5).map((match) => `${basename(match[1])}:${Number(match[2]) + 1}:${Number(match[3]) + 1}`);
+  return {
+    count: countOccurrences(text, '"uri"'),
+    samples,
+    previewText: [
+      "--- compact LSP preview ---",
+      ...samples.map((sample, index) => `${index + 1}. ${sample}`),
+      matches.length > samples.length ? `... and more in spill file` : "",
+    ].filter(Boolean).join("\n"),
+  };
+}
+
+export function extractImageSummary(content: ToolContentBlock[], text: string, details: unknown): { metadataLines: string[]; previewText: string } {
+  const mediaTypes = content
+    .filter((block) => block.type === "image")
+    .map((block) => block.source?.mediaType)
+    .filter((value): value is string => typeof value === "string");
+  const metadataLines = [
+    ...(mediaTypes.length ? [`Image types: ${Array.from(new Set(mediaTypes)).join(", ")}`] : []),
+    ...(findDimensionHints(text).length ? [`Dimensions: ${findDimensionHints(text).join(", ")}`] : []),
+  ];
+  const detailsText = details === undefined ? "" : safeJson(details).slice(0, 500);
+  const textualHints = text.split(/\r?\n/).filter((line) => line.trim() && !/base64|^[A-Za-z0-9+/=]{60,}$/.test(line)).slice(0, 6);
+  return {
+    metadataLines,
+    previewText: [
+      "--- image read summary ---",
+      ...textualHints,
+      ...(detailsText ? ["", "--- details excerpt ---", detailsText] : []),
+    ].join("\n").trim(),
+  };
+}
+
+export function extractBashSummary(text: string): { metadataLines: string[]; previewText: string } {
+  const exitCode = text.match(/exit code:?\s*(\d+)/i)?.[1];
+  const stderrHint = text.match(/stderr:?\s*(.*)/i)?.[1];
+  const metadataLines = [
+    ...(exitCode ? [`Exit code: ${exitCode}`] : []),
+    ...(stderrHint ? [`stderr hint: ${stderrHint.slice(0, 160)}`] : []),
+  ];
+  const lines = text.split(/\r?\n/);
+  const head = lines.slice(0, 20).join("\n");
+  const tail = lines.slice(-20).join("\n");
+  return {
+    metadataLines,
+    previewText: `--- head ---\n${head}\n\n--- tail ---\n${tail}`,
+  };
+}
+
+export function extractSearchSummary(text: string): { metadataLines: string[]; previewText: string } {
+  const lines = text.split(/\r?\n/).filter((line) => line.trim());
+  const matches = lines.filter((line) => /:\d+(:\d+)?:/.test(line) || /file:\/\//.test(line));
+  const metadataLines = [
+    `Approx matches: ${matches.length || lines.length}`,
+    "Tip: refine the query if you need a smaller in-context result.",
+  ];
+  return {
+    metadataLines,
+    previewText: [
+      "--- first matches ---",
+      ...lines.slice(0, 20),
+    ].join("\n"),
+  };
+}
+
+export function findDimensionHints(text: string): string[] {
+  return Array.from(new Set(Array.from(text.matchAll(/\b(\d{2,5}x\d{2,5})\b/gi)).map((match) => match[1]))).slice(0, 5);
+}