pi-tool-guard 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# pi-tool-guard
+
+A pi extension that corrects common LLM tool call mistakes: normalizes argument aliases for `edit`/`write`/`read` and strips trailing pipeline extractors from `bash` commands.
+
+## Install
+
+```bash
+pi install npm:pi-tool-guard
+```
+
+---
+
+## Features
+
+### 1. Argument alias normalization (`edit` / `write` / `read`)
+
+When the LLM calls a tool with wrong field names, the extension normalizes them before schema validation. No error, no re-execution.
+
+| Tool | Canonical | Accepted aliases |
+|---|---|---|
+| edit | `path` | `file`, `filePath`, `file_path`, `target`, `filename`, `file_name` |
+| edit | `edits[].oldText` | `old_str`, `old_string`, `oldContent`, `old`, `original`, `search` |
+| edit | `edits[].newText` | `new_str`, `new_string`, `newContent`, `new`, `replacement`, `replace` |
+| write | `path` | `file`, `filePath`, `file_path`, `target`, `filename`, `file_name` |
+| write | `content` | `text`, `body`, `code`, `data`, `fileContent`, `contents` |
+| read | `path` | `file`, `filePath`, `file_path`, `target`, `filename`, `file_name` |
+| read | `offset` | `start`, `startLine`, `start_line`, `from`, `line` |
+| read | `limit` | `lines`, `maxLines`, `max_lines`, `count`, `numLines`, `num_lines` |
+
+> **Edit tool shorthand**: top-level `oldText`/`newText` (or aliases) are automatically wrapped into an `edits` array.
+>
+> **Read tool type coercion**: string values for `offset` and `limit` are coerced to numbers.
+
+### 2. Bash pipeline extractor stripping
+
+When the LLM appends truncation commands (`tail`, `head`, `grep`, etc.) to slow commands, the extension strips them so the full output is available. This prevents the LLM from repeatedly re-running slow commands with different truncation parameters.
+
+**Three-case strategy:**
+
+| Scenario | Behavior |
+|---|---|
+| Output truncated (has `Full output: <file>`) | Run extractor on the full output file, return filtered result |
+| Fast command (< 10s), no truncation | Pipe result through extractor, return filtered result |
+| Slow command, no truncation | Return full result with notice |
+
+**Example:** `vitest run | tail -n 10`
+- If vitest output is truncated → run `tail` on the saved full output file
+- If vitest finishes in < 10s → pipe result through `tail`
+- If vitest is slow but not truncated → return full output + notice
+
+**Detected extractors:** `head`, `tail`, `grep`, `egrep`, `fgrep`, `rg`, `sed`, `awk`, `cut`, `sort`, `uniq`, `wc`, `less`, `more`, `column`, `jq`, `yq`, `tr`
+
+All trailing extractors are stripped: `npm test | grep FAIL | head -5` → strips `grep FAIL | head -5`
+
+---
+
+## Architecture
+
+Both features use `prepareArguments` on overridden built-in tools — the cleanest pi extension pattern for argument correction:
+
+- **edit/write/read**: `createXxxToolDefinition(cwd)` + `prepareArguments` normalizes aliases before schema validation
+- **bash**: `createBashToolDefinition(cwd)` + custom `execute` override:
+  1. `prepareArguments` parses the command with [unbash](https://github.com/nicolo-ribaudo/unbash), strips trailing extractors
+  2. `execute` runs the stripped command via the original built-in execute
+  3. If truncated → runs extractor on the full output file via `pi.exec`
+  4. If fast (< 10s) → pipes result through extractor via `pi.exec`
+  5. If slow → returns full result with notice
+
+No error recovery, no session scanning.

package/aliases.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from "vitest";
+import { normalizeEditArgs, normalizeWriteArgs, normalizeReadArgs } from "./aliases.ts";
+
+// ---------------------------------------------------------------------------
+// normalizeEditArgs
+// ---------------------------------------------------------------------------
+
+describe("normalizeEditArgs", () => {
+  // ── Alias renaming ───────────────────────────────────────────────────
+
+  describe("alias renaming", () => {
+    it("renames file → path", () => {
+      const args = { file: "foo.ts", edits: [{ oldText: "a", newText: "b" }] };
+      normalizeEditArgs(args);
+      expect(args).toEqual({ path: "foo.ts", edits: [{ oldText: "a", newText: "b" }] });
+    });
+
+    it("renames filePath → path", () => {
+      const args = { filePath: "foo.ts", edits: [{ oldText: "a", newText: "b" }] };
+      normalizeEditArgs(args);
+      expect(args).toHaveProperty("path", "foo.ts");
+    });
+
+    it("renames old_str → oldText inside edits", () => {
+      const args = { path: "f", edits: [{ old_str: "a", new_str: "b" }] };
+      normalizeEditArgs(args);
+      expect(args.edits[0]).toEqual({ oldText: "a", newText: "b" });
+    });
+
+    it("renames old_string → oldText", () => {
+      const args = { path: "f", edits: [{ old_string: "a", new_string: "b" }] };
+      normalizeEditArgs(args);
+      expect(args.edits[0]).toEqual({ oldText: "a", newText: "b" });
+    });
+
+    it("renames search → oldText, replace → newText", () => {
+      const args = { path: "f", edits: [{ search: "a", replace: "b" }] };
+      normalizeEditArgs(args);
+      expect(args.edits[0]).toEqual({ oldText: "a", newText: "b" });
+    });
+
+    it("renames old → oldText, new → newText", () => {
+      const args = { path: "f", edits: [{ old: "a", new: "b" }] };
+      normalizeEditArgs(args);
+      expect(args.edits[0]).toEqual({ oldText: "a", newText: "b" });
+    });
+  });
+
+  // ── Pattern A: top-level oldText/newText → wrap into edits ───────────
+
+  describe("Pattern A: top-level wrap", () => {
+    it("wraps oldText/newText into edits", () => {
+      const args = { path: "f", oldText: "a", newText: "b" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+      expect(args.oldText).toBeUndefined();
+      expect(args.newText).toBeUndefined();
+    });
+
+    it("wraps old_str/new_str aliases at top level", () => {
+      const args = { path: "f", old_str: "a", new_str: "b" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+    });
+
+    it("does NOT wrap if edits already exists", () => {
+      const args = { path: "f", edits: [{ oldText: "x", newText: "y" }], oldText: "a", newText: "b" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      // edits should keep the existing array, oldText/newText left as-is
+      expect(args.edits).toEqual([{ oldText: "x", newText: "y" }]);
+    });
+  });
+
+  // ── Pattern B: alias keys at top level → wrap ────────────────────────
+
+  describe("Pattern B: alias keys at top level", () => {
+    it("wraps search/replace at top level", () => {
+      const args = { path: "f", search: "a", replace: "b" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+    });
+
+    it("wraps old/new at top level", () => {
+      const args = { path: "f", old: "a", new: "b" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+    });
+  });
+
+  // ── Pattern C: edits as JSON string ──────────────────────────────────
+
+  describe("Pattern C: JSON string edits", () => {
+    it("parses JSON string edits", () => {
+      const args = { path: "f", edits: '[{"oldText":"a","newText":"b"}]' } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+    });
+
+    it("ignores invalid JSON", () => {
+      const args = { path: "f", edits: "not-json" } as Record<string, unknown>;
+      normalizeEditArgs(args);
+      expect(args.edits).toBe("not-json"); // unchanged
+    });
+  });
+
+  // ── No-op cases ──────────────────────────────────────────────────────
+
+  describe("no-op", () => {
+    it("already correct args pass through", () => {
+      const args = { path: "f.ts", edits: [{ oldText: "a", newText: "b" }] };
+      normalizeEditArgs(args);
+      expect(args).toEqual({ path: "f.ts", edits: [{ oldText: "a", newText: "b" }] });
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeWriteArgs
+// ---------------------------------------------------------------------------
+
+describe("normalizeWriteArgs", () => {
+  it("renames file → path", () => {
+    const args = { file: "foo.ts", content: "hello" };
+    normalizeWriteArgs(args);
+    expect(args).toEqual({ path: "foo.ts", content: "hello" });
+  });
+
+  it("renames text → content", () => {
+    const args = { path: "f", text: "hello" };
+    normalizeWriteArgs(args);
+    expect(args).toEqual({ path: "f", content: "hello" });
+  });
+
+  it("renames body → content", () => {
+    const args = { path: "f", body: "hello" };
+    normalizeWriteArgs(args);
+    expect(args).toEqual({ path: "f", content: "hello" });
+  });
+
+  it("renames code → content", () => {
+    const args = { path: "f", code: "console.log(1)" };
+    normalizeWriteArgs(args);
+    expect(args).toEqual({ path: "f", content: "console.log(1)" });
+  });
+
+  it("already correct args pass through", () => {
+    const args = { path: "f.ts", content: "hello" };
+    normalizeWriteArgs(args);
+    expect(args).toEqual({ path: "f.ts", content: "hello" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeReadArgs
+// ---------------------------------------------------------------------------
+
+describe("normalizeReadArgs", () => {
+  it("renames file → path", () => {
+    const args = { file: "foo.ts" };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "foo.ts" });
+  });
+
+  it("renames start → offset", () => {
+    const args = { path: "f", start: 10 };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f", offset: 10 });
+  });
+
+  it("renames lines → limit", () => {
+    const args = { path: "f", lines: 50 };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f", limit: 50 });
+  });
+
+  it("coerces string offset to number", () => {
+    const args = { path: "f", offset: "10" };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f", offset: 10 });
+  });
+
+  it("coerces string limit to number", () => {
+    const args = { path: "f", limit: "50" };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f", limit: 50 });
+  });
+
+  it("does not coerce non-numeric string", () => {
+    const args = { path: "f", offset: "abc" };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f", offset: "abc" }); // unchanged
+  });
+
+  it("already correct args pass through", () => {
+    const args = { path: "f.ts", offset: 1, limit: 100 };
+    normalizeReadArgs(args);
+    expect(args).toEqual({ path: "f.ts", offset: 1, limit: 100 });
+  });
+});

package/aliases.ts

@@ -0,0 +1,164 @@
+// ---------------------------------------------------------------------------
+// alias maps & normalizers for edit / write / read
+// ---------------------------------------------------------------------------
+
+export const PATH_FIELD_ALIASES = {
+  path: ["file", "filePath", "file_path", "target", "filename", "file_name"],
+} as const;
+
+export const EDIT_FIELD_ALIASES: Record<string, readonly string[]> = {
+  ...PATH_FIELD_ALIASES,
+  oldText: [
+    "old_str",
+    "old_string",
+    "old_text",
+    "oldStr",
+    "oldString",
+    "oldContent",
+    "old_content",
+    "old",
+    "original",
+    "search",
+  ],
+  newText: [
+    "new_str",
+    "new_string",
+    "new_text",
+    "newStr",
+    "newString",
+    "newContent",
+    "new_content",
+    "new",
+    "replacement",
+    "replace",
+  ],
+};
+
+export const WRITE_FIELD_ALIASES: Record<string, readonly string[]> = {
+  ...PATH_FIELD_ALIASES,
+  content: [
+    "text",
+    "body",
+    "code",
+    "data",
+    "fileContent",
+    "file_content",
+    "contents",
+  ],
+};
+
+export const READ_FIELD_ALIASES: Record<string, readonly string[]> = {
+  ...PATH_FIELD_ALIASES,
+  offset: ["start", "startLine", "start_line", "from", "line"],
+  limit: ["lines", "maxLines", "max_lines", "count", "numLines", "num_lines"],
+};
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+export const buildAliasMap = (aliases: Record<string, readonly string[]>) => {
+  const map = new Map<string, string>();
+  for (const [canonical, alts] of Object.entries(aliases)) {
+    for (const alt of alts) {
+      if (!map.has(alt)) map.set(alt, canonical);
+    }
+  }
+  return map;
+};
+
+export const editAliasMap = buildAliasMap(EDIT_FIELD_ALIASES);
+export const writeAliasMap = buildAliasMap(WRITE_FIELD_ALIASES);
+export const readAliasMap = buildAliasMap(READ_FIELD_ALIASES);
+
+export const renameAliasKeys = (
+  obj: Record<string, unknown>,
+  canonicalKeys: Record<string, readonly string[]>,
+  aliasMap: Map<string, string>,
+) => {
+  for (const [key, value] of Object.entries(obj)) {
+    const canonical = key in canonicalKeys ? key : aliasMap.get(key);
+    if (canonical && canonical !== key) {
+      obj[canonical] = value;
+      delete obj[key];
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// normalizers — mutate in place
+// ---------------------------------------------------------------------------
+
+export const normalizeEditArgs = (args: Record<string, unknown>): Record<string, unknown> => {
+  renameAliasKeys(args, EDIT_FIELD_ALIASES, editAliasMap);
+
+  // Pattern A: oldText/newText at top level (no edits array) → wrap
+  if (
+    !Array.isArray(args.edits) &&
+    typeof args.oldText === "string" &&
+    typeof args.newText === "string"
+  ) {
+    args.edits = [{ oldText: args.oldText, newText: args.newText }];
+    delete args.oldText;
+    delete args.newText;
+  }
+
+  // Pattern B: alias keys at top level → wrap into edits
+  if (!Array.isArray(args.edits)) {
+    const topOld = Object.keys(args).find((k) => editAliasMap.get(k) === "oldText");
+    const topNew = Object.keys(args).find((k) => editAliasMap.get(k) === "newText");
+    if (
+      topOld &&
+      topNew &&
+      typeof args[topOld] === "string" &&
+      typeof args[topNew] === "string"
+    ) {
+      args.edits = [{ oldText: args[topOld], newText: args[topNew] }];
+      delete args[topOld];
+      delete args[topNew];
+    }
+  }
+
+  // Pattern C: edits is a JSON string → parse it
+  if (!Array.isArray(args.edits) && typeof args.edits === "string") {
+    try {
+      const parsed = JSON.parse(args.edits);
+      if (Array.isArray(parsed)) {
+        args.edits = parsed;
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // Normalize keys inside each edit object
+  if (Array.isArray(args.edits)) {
+    for (const edit of args.edits) {
+      if (edit && typeof edit === "object") {
+        renameAliasKeys(edit as Record<string, unknown>, EDIT_FIELD_ALIASES, editAliasMap);
+      }
+    }
+  }
+
+  return args;
+};
+
+export const normalizeWriteArgs = (args: Record<string, unknown>): Record<string, unknown> => {
+  renameAliasKeys(args, WRITE_FIELD_ALIASES, writeAliasMap);
+  return args;
+};
+
+export const normalizeReadArgs = (args: Record<string, unknown>): Record<string, unknown> => {
+  renameAliasKeys(args, READ_FIELD_ALIASES, readAliasMap);
+
+  if (typeof args.offset === "string") {
+    const n = parseFloat(args.offset);
+    if (!isNaN(n)) args.offset = n;
+  }
+  if (typeof args.limit === "string") {
+    const n = parseFloat(args.limit);
+    if (!isNaN(n)) args.limit = n;
+  }
+
+  return args;
+};

package/bash.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// bash extractor execution helpers
+// ---------------------------------------------------------------------------
+
+export const FAST_THRESHOLD_MS = 10_000;
+
+export function buildNotice(removedNames: string[]): string {
+  const list = removedNames.map((r) => `\`${r}\``).join(", ");
+  return `[pi-tool-guard] Removed trailing pipeline commands: ${list}. The full output is above — do NOT re-run with different parameters.`;
+}
+
+/**
+ * Run an extractor pipeline on a file (e.g. the full output temp file).
+ * Returns the filtered text, or undefined on failure.
+ */
+export async function runExtractorOnFile(
+  pi: ExtensionAPI,
+  filePath: string,
+  pipeline: string,
+): Promise<string | undefined> {
+  try {
+    const result = await pi.exec("bash", ["-c", `cat ${JSON.stringify(filePath)} | ${pipeline}`]);
+    if (result.code === 0 && result.stdout.trim()) {
+      return result.stdout.trimEnd();
+    }
+  } catch {
+    // Bail silently
+  }
+  return undefined;
+}
+
+/**
+ * Run an extractor pipeline on inline text via printf + pipe.
+ * Returns the filtered text, or undefined on failure.
+ */
+export async function runExtractorOnText(
+  pi: ExtensionAPI,
+  text: string,
+  pipeline: string,
+): Promise<string | undefined> {
+  try {
+    const result = await pi.exec("bash", ["-c", `printf '%s' ${JSON.stringify(text)} | ${pipeline}`]);
+    if (result.code === 0) {
+      return result.stdout.trimEnd() || undefined;
+    }
+  } catch {
+    // Bail silently
+  }
+  return undefined;
+}

package/index.ts

@@ -0,0 +1,166 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  type BashToolInput,
+  type BashToolDetails,
+  type EditToolInput,
+  type ReadToolInput,
+  type WriteToolInput,
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createReadToolDefinition,
+  createWriteToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import {
+  normalizeEditArgs,
+  normalizeWriteArgs,
+  normalizeReadArgs,
+} from "./aliases.ts";
+import {
+  stripTrailingExtractors,
+  extractFullOutputPath,
+} from "./pipeline.ts";
+import {
+  FAST_THRESHOLD_MS,
+  buildNotice,
+  runExtractorOnFile,
+  runExtractorOnText,
+} from "./bash.ts";
+
+// ---------------------------------------------------------------------------
+// extension
+// ---------------------------------------------------------------------------
+
+export default function toolGuardExtension(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    // ── Override edit ──────────────────────────────────────────────────
+    pi.registerTool({
+      ...createEditToolDefinition(ctx.cwd),
+      prepareArguments: (args: unknown): EditToolInput => {
+        if (args && typeof args === "object") {
+          normalizeEditArgs(args as Record<string, unknown>);
+        }
+        return args as EditToolInput;
+      },
+    });
+
+    // ── Override write ─────────────────────────────────────────────────
+    pi.registerTool({
+      ...createWriteToolDefinition(ctx.cwd),
+      prepareArguments: (args: unknown): WriteToolInput => {
+        if (args && typeof args === "object") {
+          normalizeWriteArgs(args as Record<string, unknown>);
+        }
+        return args as WriteToolInput;
+      },
+    });
+
+    // ── Override read ──────────────────────────────────────────────────
+    pi.registerTool({
+      ...createReadToolDefinition(ctx.cwd),
+      prepareArguments: (args: unknown): ReadToolInput => {
+        if (args && typeof args === "object") {
+          normalizeReadArgs(args as Record<string, unknown>);
+        }
+        return args as ReadToolInput;
+      },
+    });
+
+    // ── Override bash ──────────────────────────────────────────────────
+    const bashDef = createBashToolDefinition(ctx.cwd);
+    const originalExecute = bashDef.execute;
+
+    pi.registerTool({
+      ...bashDef,
+      prepareArguments: (args: unknown): BashToolInput => {
+        if (!args || typeof args !== "object") return args as BashToolInput;
+
+        const input = args as Record<string, unknown>;
+        if (typeof input.command !== "string") return args as BashToolInput;
+
+        const stripped = stripTrailingExtractors(input.command);
+        if (stripped) {
+          input.command = stripped.cleaned;
+          input._piToolGuardRemoved = stripped.removedNames;
+          input._piToolGuardPipeline = stripped.removedPipeline;
+        }
+
+        return input as unknown as BashToolInput;
+      },
+
+      async execute(toolCallId, params, signal, onUpdate, execCtx) {
+        const input = params as Record<string, unknown>;
+        const removedNames = input._piToolGuardRemoved as string[] | undefined;
+        const removedPipeline = input._piToolGuardPipeline as string | undefined;
+
+        // No extractors — run normally
+        if (!removedNames || removedNames.length === 0 || !removedPipeline) {
+          return originalExecute(toolCallId, params, signal, onUpdate, execCtx);
+        }
+
+        // Clean transient fields before running
+        delete input._piToolGuardRemoved;
+        delete input._piToolGuardPipeline;
+
+        // Run the stripped command
+        const start = Date.now();
+        let result;
+        try {
+          result = await originalExecute(toolCallId, params, signal, onUpdate, execCtx);
+        } catch (err) {
+          // On error: check if output was saved to file, run extractor on it
+          const errText = err instanceof Error ? err.message : String(err);
+          const fullPath = extractFullOutputPath(errText);
+          if (fullPath) {
+            const extracted = await runExtractorOnFile(pi, fullPath, removedPipeline);
+            if (extracted !== undefined) {
+              const notice = buildNotice(removedNames);
+              throw new Error(`${extracted}\n\n${notice}`);
+            }
+          }
+          throw err;
+        }
+
+        const elapsed = Date.now() - start;
+
+        // Case 1: Output was truncated → run extractor on the full output file
+        const details = result.details as BashToolDetails | undefined;
+        if (details?.fullOutputPath) {
+          const extracted = await runExtractorOnFile(pi, details.fullOutputPath, removedPipeline);
+          if (extracted !== undefined) {
+            const notice = buildNotice(removedNames);
+            return {
+              content: [{ type: "text" as const, text: `${extracted}\n\n${notice}` }],
+              details: result.details,
+            };
+          }
+        }
+
+        // Case 2: Fast command, no truncation → pipe result through extractor
+        if (elapsed < FAST_THRESHOLD_MS) {
+          const resultText = result.content
+            .filter((c): c is { type: "text"; text: string } => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+
+          const extracted = await runExtractorOnText(pi, resultText, removedPipeline);
+          if (extracted !== undefined) {
+            const notice = buildNotice(removedNames);
+            return {
+              content: [{ type: "text" as const, text: `${extracted}\n\n${notice}` }],
+              details: result.details,
+            };
+          }
+        }
+
+        // Case 3: Slow, no truncation → return full result with notice
+        const notice = buildNotice(removedNames);
+        return {
+          content: [...result.content, { type: "text" as const, text: `\n\n${notice}` }],
+          details: result.details,
+        };
+      },
+    });
+
+    ctx.ui.notify("pi-tool-guard: overriding edit/write/read/bash with corrections", "info");
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-tool-guard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension that corrects LLM tool calls: normalizes argument aliases for edit/write/read and strips trailing pipeline extractors from bash commands",
+  "main": "index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "argument-normalization",
+    "alias-correction",
+    "tool-override",
+    "pipeline-optimization"
+  ],
+  "author": "Jiajun Chen <tychenjiajun@gmail.com>",
+  "license": "MIT",
+  "files": [
+    "*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.79.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "packageManager": "pnpm@11.6.0",
+  "dependencies": {
+    "unbash": "^4.0.1"
+  }
+}

package/pipeline.test.ts

@@ -0,0 +1,346 @@
+import { describe, it, expect } from "vitest";
+import { stripTrailingExtractors, extractFullOutputPath } from "./pipeline.ts";
+
+// ---------------------------------------------------------------------------
+// Real-world cases from ~/.pi/agent/sessions/
+// ---------------------------------------------------------------------------
+
+describe("stripTrailingExtractors", () => {
+
+  // ── Simple tail/head ─────────────────────────────────────────────────
+
+  describe("simple tail/head", () => {
+    it("npm run build 2>&1 | tail -20", () => {
+      const r = stripTrailingExtractors("npm run build 2>&1 | tail -20");
+      expect(r).toEqual({
+        cleaned: "npm run build 2>&1",
+        removedNames: ["tail"],
+        removedPipeline: "tail -20",
+      });
+    });
+
+    it("npm run build 2>&1 | tail -5", () => {
+      const r = stripTrailingExtractors("npm run build 2>&1 | tail -5");
+      expect(r!.cleaned).toBe("npm run build 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("npm run build 2>&1 | tail -30", () => {
+      const r = stripTrailingExtractors("npm run build 2>&1 | tail -30");
+      expect(r!.cleaned).toBe("npm run build 2>&1");
+    });
+
+    it("npm run typecheck 2>&1 && npm run build 2>&1 | tail -5", () => {
+      const r = stripTrailingExtractors("npm run typecheck 2>&1 && npm run build 2>&1 | tail -5");
+      expect(r).toBeDefined();
+      expect(r!.removedNames).toEqual(["tail"]);
+      expect(r!.cleaned).toBe("npm run typecheck 2>&1 && npm run build 2>&1");
+    });
+
+    it("find src -type f -name '*.ts' | head -20", () => {
+      const r = stripTrailingExtractors("find src -type f -name '*.ts' | head -20");
+      expect(r).toEqual({
+        cleaned: "find src -type f -name '*.ts'",
+        removedNames: ["head"],
+        removedPipeline: "head -20",
+      });
+    });
+
+    it("./dist/cli.js 2>&1 | head -30", () => {
+      const r = stripTrailingExtractors("./dist/cli.js 2>&1 | head -30");
+      expect(r!.cleaned).toBe("./dist/cli.js 2>&1");
+      expect(r!.removedNames).toEqual(["head"]);
+    });
+  });
+
+  // ── pytest patterns (the main anti-pattern) ──────────────────────────
+
+  describe("pytest with tail/head", () => {
+    it(".venv/bin/python -m pytest tests/ -v --tb=short 2>&1 | tail -30", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/ -v --tb=short 2>&1 | tail -30");
+      expect(r!.cleaned).toBe(".venv/bin/python -m pytest tests/ -v --tb=short 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("pytest with -xvs and tail -60 (repeated anti-pattern)", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/test_time_varying_universe_equivalence.py::TestTimeVaryingUniverseEquivalence::test_metrics_equivalence -xvs 2>&1 | tail -60");
+      expect(r!.cleaned).toContain("test_metrics_equivalence -xvs 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("pytest with -xvs and tail -80 (same test, bigger tail)", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/test_time_varying_universe_equivalence.py::TestTimeVaryingUniverseEquivalence::test_metrics_equivalence -xvs 2>&1 | tail -80");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("pytest with tail -100", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/ -x -q --tb=short 2>&1 | tail -100");
+      expect(r!.cleaned).toBe(".venv/bin/python -m pytest tests/ -x -q --tb=short 2>&1");
+    });
+
+    it("pytest with head -100", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/ -v --tb=short 2>&1 | head -100");
+      expect(r!.cleaned).toBe(".venv/bin/python -m pytest tests/ -v --tb=short 2>&1");
+      expect(r!.removedNames).toEqual(["head"]);
+    });
+
+    it("pytest with head -50", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/test_metric_caching_and_list.py -v --tb=short 2>&1 | head -50");
+      expect(r!.removedNames).toEqual(["head"]);
+    });
+
+    it("pytest with head -80", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/test_metric_caching_and_list.py -v --tb=short 2>&1 | head -80");
+      expect(r!.removedNames).toEqual(["head"]);
+    });
+
+    it("pytest with tail -5", () => {
+      const r = stripTrailingExtractors("cd /Users/chenjiajun/projects/insight-alpha-server-qlib && uv run pytest -v 2>&1 | tail -5");
+      expect(r).toBeDefined();
+      expect(r!.cleaned).toBe("cd /Users/chenjiajun/projects/insight-alpha-server-qlib && uv run pytest -v 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+  });
+
+  // ── pytest with grep (context lines) ─────────────────────────────────
+
+  describe("pytest with grep -A (context lines)", () => {
+    it("pytest | grep -A 50 FAILED", () => {
+      const r = stripTrailingExtractors('.venv/bin/python -m pytest tests/test_group_return_with_benchmark.py::TestBenchmarkEquivalence::test_benchmark_data_matches -v 2>&1 | grep -A 50 "FAILED"');
+      expect(r!.cleaned).toContain("test_benchmark_data_matches -v 2>&1");
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+
+    it("pytest | grep -A 100 FAILED", () => {
+      const r = stripTrailingExtractors('.venv/bin/python -m pytest tests/test_group_return_with_benchmark.py::TestBenchmarkEquivalence::test_benchmark_data_matches -v 2>&1 | grep -A 100 "FAILED"');
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+
+    it("pytest | grep -A 30 pattern", () => {
+      const r = stripTrailingExtractors('.venv/bin/python -m pytest tests/test_group_return_with_benchmark.py::TestBenchmarkEquivalence::test_group_return_benchmark_matches_standalone -v 2>&1 | grep -A 30 "assert"');
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+
+    it("pytest | grep -A 10 pattern", () => {
+      const r = stripTrailingExtractors('.venv/bin/python -m pytest tests/test_time_varying_universe_equivalence.py::TestTimeVaryingUniverseEquivalence::test_metrics_equivalence -xvs 2>&1 | grep -A 10 "Error"');
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+
+    it("pytest | grep -A 5 pattern", () => {
+      const r = stripTrailingExtractors('.venv/bin/python -m pytest tests/test_time_varying_universe_equivalence.py::TestTimeVaryingUniverseEquivalence::test_metrics_equivalence -xvs 2>&1 | grep -A 5 "assert"');
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+  });
+
+  // ── Multi-pipe extractors ────────────────────────────────────────────
+
+  describe("multi-pipe extractors", () => {
+    it("npm test | grep FAIL | head -5", () => {
+      const r = stripTrailingExtractors("npm test | grep FAIL | head -5");
+      expect(r).toEqual({
+        cleaned: "npm test",
+        removedNames: ["grep", "head"],
+        removedPipeline: "grep FAIL | head -5",
+      });
+    });
+
+    it("cmd | grep -v grep | head -5", () => {
+      const r = stripTrailingExtractors("ps aux | grep uvicorn | grep -v grep");
+      // grep -v grep is also grep — should be stripped
+      if (r) {
+        expect(r.removedNames).toEqual(["grep", "grep"]);
+      }
+    });
+  });
+
+  // ── Complex pipelines ────────────────────────────────────────────────
+
+  describe("complex pipelines", () => {
+    it("curl | python json.tool | head -40", () => {
+      const r = stripTrailingExtractors("curl -s http://localhost:8000/tasks 2>&1 | python3 -m json.tool 2>&1 | head -30");
+      // python3 -m json.tool is not an extractor, head is
+      if (r) {
+        expect(r.removedNames).toEqual(["head"]);
+        expect(r.cleaned).toContain("python3 -m json.tool 2>&1");
+      }
+    });
+
+    it("cat | cat -v | head -10", () => {
+      const r = stripTrailingExtractors("head -c 2000 /tmp/file.js | cat -v | head -10");
+      if (r) {
+        expect(r.removedNames).toEqual(["head"]);
+      }
+    });
+
+    it("grep -oE | sort -u | head -40", () => {
+      const r = stripTrailingExtractors("grep -oE '[a-zA-Z_$][a-zA-Z0-9_$]{4,}' /tmp/file.js | sort -u | head -40");
+      if (r) {
+        // sort -u is an extractor, head is too
+        expect(r.removedNames).toContain("head");
+      }
+    });
+
+    it("sed | cat -n", () => {
+      const r = stripTrailingExtractors("sed -n '130,140p' /path/to/file.ts | cat -n");
+      // cat is not an extractor
+      expect(r).toBeUndefined();
+    });
+
+    it("npm build | grep | head (multi-step)", () => {
+      const r = stripTrailingExtractors("pnpm build:css 2>&1 && grep 'color-tag' styles/theme.css | grep -v 'on' | head -10");
+      if (r) {
+        expect(r.removedNames).toContain("head");
+      }
+    });
+  });
+
+  // ── Non-pipeline commands (should return undefined) ──────────────────
+
+  describe("non-pipeline commands", () => {
+    it("simple ls", () => {
+      expect(stripTrailingExtractors("ls -la")).toBeUndefined();
+    });
+
+    it("simple cat", () => {
+      expect(stripTrailingExtractors("cat file.txt")).toBeUndefined();
+    });
+
+    it("simple npm test", () => {
+      expect(stripTrailingExtractors("npm test")).toBeUndefined();
+    });
+
+    it("simple pytest", () => {
+      expect(stripTrailingExtractors(".venv/bin/python -m pytest tests/ -v")).toBeUndefined();
+    });
+
+    it("cd && command", () => {
+      expect(stripTrailingExtractors("cd /tmp && npm install")).toBeUndefined();
+    });
+  });
+
+  // ── Pipeline with non-extractor at end ───────────────────────────────
+
+  describe("pipeline with non-extractor at end", () => {
+    it("echo hello | cat", () => {
+      expect(stripTrailingExtractors("echo hello | cat")).toBeUndefined();
+    });
+
+    it("cat file | sort", () => {
+      // sort IS an extractor
+      const r = stripTrailingExtractors("cat file | sort");
+      expect(r).toBeDefined();
+      expect(r!.removedNames).toEqual(["sort"]);
+    });
+
+    it("cat file | wc -l", () => {
+      // wc IS an extractor
+      const r = stripTrailingExtractors("cat file | wc -l");
+      expect(r).toBeDefined();
+      expect(r!.removedNames).toEqual(["wc"]);
+    });
+  });
+
+  // ── Commands with 2>&1 ───────────────────────────────────────────────
+
+  describe("stderr redirection", () => {
+    it("cmd 2>&1 | tail -30", () => {
+      const r = stripTrailingExtractors(".venv/bin/python -m pytest tests/test_factor.py -v --tb=short 2>&1 | tail -40");
+      expect(r!.cleaned).toBe(".venv/bin/python -m pytest tests/test_factor.py -v --tb=short 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("pnpm install 2>&1 | tail -5", () => {
+      const r = stripTrailingExtractors("cd /tmp/resume-test && pnpm install 2>&1 | tail -5");
+      expect(r).toBeDefined();
+      expect(r!.cleaned).toBe("cd /tmp/resume-test && pnpm install 2>&1");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+  });
+
+  // ── view-logs and scripts ────────────────────────────────────────────
+
+  describe("script pipelines", () => {
+    it("./view-logs.sh all | tail -80", () => {
+      const r = stripTrailingExtractors("./view-logs.sh all | tail -80");
+      expect(r!.cleaned).toBe("./view-logs.sh all");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("./view-logs.sh all | grep -i pattern", () => {
+      const r = stripTrailingExtractors('./view-logs.sh all | grep -i "error"');
+      expect(r!.cleaned).toBe("./view-logs.sh all");
+      expect(r!.removedNames).toEqual(["grep"]);
+    });
+
+    it("cat /tmp/server.log | tail -100", () => {
+      const r = stripTrailingExtractors("cat /tmp/server.log 2>/dev/null | tail -100");
+      expect(r!.removedNames).toEqual(["tail"]);
+    });
+
+    it("tail -30 /tmp/server.log (standalone tail, not pipeline)", () => {
+      // This is NOT a pipeline — tail is the only command
+      expect(stripTrailingExtractors("tail -30 /tmp/server.log")).toBeUndefined();
+    });
+  });
+
+  // ── Edge cases ───────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("empty string", () => {
+      expect(stripTrailingExtractors("")).toBeUndefined();
+    });
+
+    it("whitespace only", () => {
+      expect(stripTrailingExtractors("   ")).toBeUndefined();
+    });
+
+    it("single pipe with non-extractor", () => {
+      expect(stripTrailingExtractors("echo hello | cat")).toBeUndefined();
+    });
+
+    it("command with env vars", () => {
+      const r = stripTrailingExtractors("PAT_TOKEN=abc ./scripts/calc.py 2>&1 | head -50");
+      expect(r!.removedNames).toEqual(["head"]);
+    });
+
+    it("command with && before pipe", () => {
+      const r = stripTrailingExtractors("cd /path && npm test 2>&1 | tail -20");
+      expect(r).toBeDefined();
+      expect(r!.removedNames).toEqual(["tail"]);
+      expect(r!.cleaned).toBe("cd /path && npm test 2>&1");
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractFullOutputPath
+// ---------------------------------------------------------------------------
+
+describe("extractFullOutputPath", () => {
+  it("extracts path from truncated output", () => {
+    const text = "some output\n\n[Showing lines 1-100 of 500. Full output: /tmp/pi-bash-abc123]";
+    expect(extractFullOutputPath(text)).toBe("/tmp/pi-bash-abc123");
+  });
+
+  it("extracts path from bytes-limited truncation", () => {
+    const text = "some output\n\n[Showing lines 1-100 of 500 (50KB limit). Full output: /tmp/pi-bash-xyz]";
+    expect(extractFullOutputPath(text)).toBe("/tmp/pi-bash-xyz");
+  });
+
+  it("extracts path from last-line truncation", () => {
+    const text = "output\n\n[Showing last 50KB of line 500 (line is 1.2MB). Full output: /tmp/pi-bash-foo]";
+    expect(extractFullOutputPath(text)).toBe("/tmp/pi-bash-foo");
+  });
+
+  it("returns undefined for non-truncated output", () => {
+    expect(extractFullOutputPath("no truncation here")).toBeUndefined();
+  });
+
+  it("returns undefined for error without truncation", () => {
+    expect(extractFullOutputPath("error output\n\nCommand exited with code 1")).toBeUndefined();
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(extractFullOutputPath("")).toBeUndefined();
+  });
+});

package/pipeline.ts

@@ -0,0 +1,105 @@
+import { parse } from "unbash";
+
+// ---------------------------------------------------------------------------
+// pipeline extractor stripping (unbash AST)
+// ---------------------------------------------------------------------------
+
+export const EXTRACTOR_COMMANDS = new Set([
+  "head",
+  "tail",
+  "grep",
+  "egrep",
+  "fgrep",
+  "rg",
+  "sed",
+  "awk",
+  "cut",
+  "sort",
+  "uniq",
+  "wc",
+  "less",
+  "more",
+  "column",
+  "jq",
+  "yq",
+  "tr",
+]);
+
+export function isExtractor(name: string): boolean {
+  return EXTRACTOR_COMMANDS.has(name);
+}
+
+export interface StripResult {
+  cleaned: string;
+  removedNames: string[];
+  removedPipeline: string;
+}
+
+/**
+ * Parse a bash command, find trailing extractor commands in pipelines,
+ * strip them, and return the cleaned command + pipeline segments.
+ * Returns undefined if nothing was changed.
+ */
+export function stripTrailingExtractors(command: string): StripResult | undefined {
+  let ast;
+  try {
+    ast = parse(command);
+  } catch {
+    return undefined;
+  }
+
+  const stmt = ast.commands[0];
+  if (!stmt) return undefined;
+
+  // Walk into AndOr → Pipeline → commands
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let inner: any = stmt.command;
+  while (inner && inner.type === "AndOr") {
+    const lastCmd = inner.commands[inner.commands.length - 1];
+    if (!lastCmd) return undefined;
+    inner = lastCmd;
+  }
+
+  if (!inner || inner.type !== "Pipeline") return undefined;
+
+  const cmds = inner.commands;
+  if (cmds.length < 2) return undefined;
+
+  // Walk backward, collect trailing extractors
+  const removedNames: string[] = [];
+  let stripFrom = cmds.length;
+
+  for (let i = cmds.length - 1; i >= 1; i--) {
+    const cmd = cmds[i]!;
+    if (cmd.type !== "Command") break;
+    const name = cmd.name?.text;
+    if (name && isExtractor(name)) {
+      removedNames.unshift(name);
+      stripFrom = i;
+    } else {
+      break;
+    }
+  }
+
+  if (stripFrom === cmds.length) return undefined;
+
+  const prevCmd = cmds[stripFrom - 1]!;
+  const cleaned = command.slice(0, prevCmd.end).trim();
+  if (!cleaned) return undefined;
+
+  // Reconstruct the removed pipeline part (e.g. "grep FAIL | head -5")
+  const removedPipeline = cmds
+    .slice(stripFrom)
+    .map((c: { pos: number; end: number }) => command.slice(c.pos, c.end))
+    .join(" | ");
+
+  return { cleaned, removedNames, removedPipeline };
+}
+
+/**
+ * Extract "Full output: <path>" from bash result text.
+ */
+export function extractFullOutputPath(text: string): string | undefined {
+  const match = text.match(/\bFull output:\s*(\S+?)\]?$/m);
+  return match?.[1];
+}