@jaggerxtrm/pi-extensions 0.7.17 → 0.7.21

package/README.md

@@ -41,3 +41,10 @@ Pi discovers this package through:
 - `pi.extensions: ["./src/index.ts"]`
 
 After install, keep `.pi/settings.json` package wiring pointed at `npm:@jaggerxtrm/pi-extensions`.
+
+## Managed extensions
+
+Notable bundled extensions include:
+
+- `xtrm-ui` — XTRM Pi chrome, native tool summaries, selectable external tool chrome (`/xtrm-ui chrome background|box`).
+- `sp-terminal-overlay` — `/sp-feed`, `/sp-ps`, and `/xtrm-terminal` streaming overlays for specialist monitoring.

package/extensions/README.md

@@ -3,3 +3,15 @@
 This directory is the canonical source for managed Pi extension entrypoints.
 
 Runtime delivery is package-based via `npm:@jaggerxtrm/pi-extensions`.
+
+## sp-terminal-overlay
+
+Streaming terminal-style overlay for specialist/process monitoring commands.
+
+Commands:
+
+- `/sp-feed [args]` — opens `sp feed -f [args]` in an overlay.
+- `/sp-ps [args]` / `/xtrm-ps [args]` — opens `sp ps [args]` (defaults to `sp ps --follow`) in an overlay.
+- `/xtrm-terminal <command>` — opens an arbitrary shell command in an overlay.
+
+Keys: `Esc`/`q` close, `r` restart, arrows/page keys scroll.

package/extensions/sp-terminal-overlay/index.ts

@@ -0,0 +1,495 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+const MAX_BUFFER_LINES = 2000;
+const DEFAULT_VISIBLE_LINES = 24;
+const RENDER_THROTTLE_MS = 100;
+const ANSI_SGR_PATTERN = /^\x1b\[[0-9;]*m$/u;
+const DISALLOWED_SGR_CODES = new Set([5, 6, 8]);
+
+function padVisible(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - visibleWidth(text)));
+}
+
+function resetAnsi(text: string): string {
+  return text.includes("\x1b") ? `${text}\x1b[0m` : text;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function resolveSpFeedCommand(args: string): string {
+  const trimmed = args.trim();
+  return trimmed ? `sp feed -f ${trimmed}` : "sp feed -f";
+}
+
+function resolveSpPsCommand(args: string): string {
+  const trimmed = args.trim();
+  return trimmed ? `sp ps ${trimmed}` : "sp ps --follow";
+}
+
+function openTerminalOverlay(ctx: ExtensionCommandContext, title: string, command: string): Promise<void> {
+  return ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) => {
+      const terminal = new StreamingTerminalOverlay({
+        title,
+        command,
+        cwd: process.cwd(),
+        theme,
+        requestRender: () => {
+          tui.requestRender();
+        },
+        close: () => {
+          terminal.dispose();
+          done(undefined);
+        },
+      });
+      return terminal;
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "80%",
+        minWidth: 72,
+        maxHeight: "80%",
+        margin: 1,
+      },
+    } as Parameters<ExtensionCommandContext["ui"]["custom"]>[1],
+  ).then(() => undefined);
+}
+
+type StreamingTerminalOverlayOptions = {
+  title: string;
+  command: string;
+  cwd: string;
+  theme: Theme;
+  requestRender: () => void;
+  close: () => void;
+};
+
+class StreamingTerminalOverlay {
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private lines: string[] = [];
+  private currentLine = "";
+  private screenLines: string[] = [];
+  private cursorRow = 0;
+  private cursorCol = 0;
+  private terminalMode = false;
+  private scrollOffset = 0;
+  private status = "starting";
+  private closed = false;
+  private renderTimer: ReturnType<typeof setTimeout> | undefined;
+  private lastRenderAt = 0;
+
+  constructor(private readonly options: StreamingTerminalOverlayOptions) {
+    this.start();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q") || matchesKey(data, "ctrl+c")) {
+      this.options.close();
+      return;
+    }
+    if (matchesKey(data, "r")) {
+      this.restart();
+      return;
+    }
+    if (matchesKey(data, "up")) {
+      this.scrollOffset = Math.min(this.scrollOffset + 1, Math.max(0, this.renderSourceLines().length - 1));
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, "down")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, "pageup")) {
+      this.scrollOffset = Math.min(this.scrollOffset + DEFAULT_VISIBLE_LINES, Math.max(0, this.renderSourceLines().length - 1));
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, "pagedown")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - DEFAULT_VISIBLE_LINES);
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, "home")) {
+      this.scrollOffset = Math.max(0, this.renderSourceLines().length - 1);
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, "end")) {
+      this.scrollOffset = 0;
+      this.options.requestRender();
+    }
+  }
+
+  render(width: number): string[] {
+    const theme = this.options.theme;
+    const overlayWidth = Math.max(40, width);
+    const innerWidth = overlayWidth - 2;
+    const contentWidth = Math.max(1, innerWidth - 2);
+    const allLines = this.renderSourceLines();
+    const visibleCount = DEFAULT_VISIBLE_LINES;
+    const end = Math.max(0, allLines.length - this.scrollOffset);
+    const start = Math.max(0, end - visibleCount);
+    const visible = allLines.slice(start, end);
+    const hiddenAbove = start;
+    const hiddenBelow = Math.max(0, allLines.length - end);
+
+    const border = (text: string) => theme.fg("border", text);
+    const title = ` ${theme.fg("accent", theme.bold(this.options.title))} ${theme.fg("dim", this.status)} `;
+    const top = border("╭") + truncateToWidth(title, Math.max(0, innerWidth), "") + border("─".repeat(Math.max(0, innerWidth - visibleWidth(title)))) + border("╮");
+    const row = (content: string) => {
+      const truncated = resetAnsi(truncateToWidth(content, contentWidth));
+      return `${border("│")} ${padVisible(truncated, contentWidth)} ${border("│")}`;
+    };
+
+    const output = [top];
+    output.push(row(theme.fg("dim", `$ ${this.options.command}`)));
+    output.push(row(theme.fg("dim", "Esc/q close • r restart • ↑↓ scroll • PgUp/PgDn page")));
+    output.push(row(""));
+    const bodyRows: string[] = [];
+    if (hiddenAbove > 0) bodyRows.push(theme.fg("dim", `… ${hiddenAbove} lines above`));
+    bodyRows.push(...visible);
+    if (visible.length === 0) bodyRows.push(theme.fg("dim", "waiting for output…"));
+    if (hiddenBelow > 0) bodyRows.push(theme.fg("dim", `… ${hiddenBelow} lines below`));
+
+    for (let index = 0; index < visibleCount; index++) {
+      output.push(row(bodyRows[index] ?? ""));
+    }
+    output.push(border("╰" + "─".repeat(innerWidth) + "╯"));
+    return output;
+  }
+
+  invalidate(): void {}
+
+  dispose(): void {
+    this.closed = true;
+    if (this.renderTimer) clearTimeout(this.renderTimer);
+    this.renderTimer = undefined;
+    this.stop();
+  }
+
+  private start(): void {
+    this.stop();
+    this.status = "running";
+    this.lines = [];
+    this.currentLine = "";
+    this.screenLines = [];
+    this.cursorRow = 0;
+    this.cursorCol = 0;
+    this.terminalMode = false;
+    this.scrollOffset = 0;
+
+    const shell = process.env.SHELL || "/bin/sh";
+    this.child = spawn(shell, ["-lc", this.options.command], {
+      cwd: this.options.cwd,
+      env: {
+        ...process.env,
+        FORCE_COLOR: process.env.FORCE_COLOR ?? "1",
+        TERM: process.env.TERM ?? "xterm-256color",
+        COLUMNS: process.env.COLUMNS ?? "120",
+        LINES: process.env.LINES ?? "40",
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    this.child.stdout.on("data", (chunk) => this.append(String(chunk)));
+    this.child.stderr.on("data", (chunk) => this.append(String(chunk)));
+    this.child.on("error", (error) => {
+      this.status = "error";
+      this.append(`\n[error] ${error.message}\n`);
+    });
+    this.child.on("close", (code, signal) => {
+      this.flushCurrentLine();
+      this.status = signal ? `stopped (${signal})` : `exited ${code ?? "unknown"}`;
+      this.requestRenderSoon(true);
+    });
+
+    this.requestRenderSoon(true);
+  }
+
+  private restart(): void {
+    this.start();
+  }
+
+  private stop(): void {
+    const child = this.child;
+    this.child = undefined;
+    if (child && !child.killed) {
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!child.killed) child.kill("SIGKILL");
+      }, 750).unref?.();
+    }
+  }
+
+  private requestRenderSoon(immediate = false): void {
+    if (this.closed) return;
+    if (immediate) {
+      if (this.renderTimer) clearTimeout(this.renderTimer);
+      this.renderTimer = undefined;
+      this.lastRenderAt = Date.now();
+      this.options.requestRender();
+      return;
+    }
+
+    const now = Date.now();
+    const elapsed = now - this.lastRenderAt;
+    if (elapsed >= RENDER_THROTTLE_MS) {
+      this.lastRenderAt = now;
+      this.options.requestRender();
+      return;
+    }
+
+    if (this.renderTimer) return;
+    this.renderTimer = setTimeout(() => {
+      this.renderTimer = undefined;
+      this.lastRenderAt = Date.now();
+      this.options.requestRender();
+    }, RENDER_THROTTLE_MS - elapsed);
+    this.renderTimer.unref?.();
+  }
+
+  private renderSourceLines(): string[] {
+    if (this.terminalMode) {
+      return this.screenLines.map((line) => line.replace(/\s+$/u, ""));
+    }
+    return this.currentLine ? [...this.lines, this.currentLine] : this.lines;
+  }
+
+  private append(text: string): void {
+    if (this.closed) return;
+    for (let index = 0; index < text.length; index++) {
+      const char = text[index]!;
+      if (char === "\x1b") {
+        const sgrMatch = text.slice(index).match(/^\x1b\[[0-9;]*m/u);
+        if (sgrMatch?.[0]) {
+          this.appendSafeSgr(sgrMatch[0]);
+          index += sgrMatch[0].length - 1;
+          continue;
+        }
+        const nextIndex = this.consumeEscape(text, index);
+        if (nextIndex !== index) {
+          index = nextIndex;
+          continue;
+        }
+      }
+      this.appendChar(char);
+    }
+    this.trimBuffer();
+    this.requestRenderSoon();
+  }
+
+  private appendSafeSgr(sequence: string): void {
+    if (!ANSI_SGR_PATTERN.test(sequence)) return;
+    const params = sequence.slice(2, -1).split(";").filter(Boolean).map((part) => Number.parseInt(part, 10));
+    if (params.some((param) => Number.isNaN(param) || DISALLOWED_SGR_CODES.has(param))) return;
+
+    // Cursor-addressed dashboards need cell-aware mutation. Keeping raw SGR inside
+    // screenLines makes cursorCol slicing unsafe, so preserve colors only for
+    // append-only feed output.
+    if (this.terminalMode) return;
+    this.currentLine += sequence;
+  }
+
+  private appendChar(char: string): void {
+    if (char === "\r") {
+      if (this.terminalMode) this.cursorCol = 0;
+      else this.currentLine = "";
+      return;
+    }
+    if (char === "\n") {
+      if (this.terminalMode) {
+        this.cursorRow++;
+        this.cursorCol = 0;
+        this.ensureScreenLine(this.cursorRow);
+      } else {
+        this.flushCurrentLine();
+      }
+      return;
+    }
+    if (char === "\b" || char === "\x7f") {
+      if (this.terminalMode) this.cursorCol = Math.max(0, this.cursorCol - 1);
+      else this.currentLine = this.currentLine.slice(0, -1);
+      return;
+    }
+    if (char < " " && char !== "\t") return;
+
+    if (this.terminalMode) {
+      this.writeScreenChar(char === "\t" ? " " : char);
+      return;
+    }
+    this.currentLine += char;
+  }
+
+  private consumeEscape(text: string, start: number): number {
+    const introducer = text[start + 1];
+    if (introducer === "[") {
+      let end = start + 2;
+      while (end < text.length && !/[A-Za-z~]/.test(text[end]!)) end++;
+      if (end >= text.length) return start;
+      this.handleCsi(text.slice(start + 2, end), text[end]!);
+      return end;
+    }
+    if (introducer === "]") {
+      let end = start + 2;
+      while (end < text.length) {
+        if (text[end] === "\x07") return end;
+        if (text[end] === "\x1b" && text[end + 1] === "\\") return end + 1;
+        end++;
+      }
+      return start;
+    }
+    if (introducer) return start + 1;
+    return start;
+  }
+
+  private handleCsi(params: string, final: string): void {
+    const numbers = params
+      .replace(/[?>!]/g, "")
+      .split(";")
+      .map((part) => Number.parseInt(part || "0", 10));
+    const first = numbers[0] ?? 0;
+
+    if (final === "m") return;
+    if (final === "H" || final === "f") {
+      this.enterTerminalMode();
+      this.cursorRow = Math.max(0, (numbers[0] || 1) - 1);
+      this.cursorCol = Math.max(0, (numbers[1] || 1) - 1);
+      this.ensureScreenLine(this.cursorRow);
+      return;
+    }
+    if (final === "J") {
+      this.enterTerminalMode();
+      if (first === 2 || first === 3) {
+        this.screenLines = [];
+        this.cursorRow = 0;
+        this.cursorCol = 0;
+        this.ensureScreenLine(0);
+      } else if (first === 0) {
+        this.screenLines = this.screenLines.slice(0, this.cursorRow + 1);
+        this.clearScreenLineFromCursor();
+      }
+      return;
+    }
+    if (final === "K") {
+      this.enterTerminalMode();
+      if (first === 2) this.screenLines[this.cursorRow] = "";
+      else this.clearScreenLineFromCursor();
+      return;
+    }
+    if (final === "A") {
+      this.enterTerminalMode();
+      this.cursorRow = Math.max(0, this.cursorRow - Math.max(1, first));
+      return;
+    }
+    if (final === "B") {
+      this.enterTerminalMode();
+      this.cursorRow += Math.max(1, first);
+      this.ensureScreenLine(this.cursorRow);
+      return;
+    }
+    if (final === "C") {
+      this.enterTerminalMode();
+      this.cursorCol += Math.max(1, first);
+      return;
+    }
+    if (final === "D") {
+      this.enterTerminalMode();
+      this.cursorCol = Math.max(0, this.cursorCol - Math.max(1, first));
+    }
+  }
+
+  private enterTerminalMode(): void {
+    if (this.terminalMode) return;
+    this.terminalMode = true;
+    this.screenLines = this.currentLine ? [...this.lines, this.currentLine] : [...this.lines];
+    if (this.screenLines.length === 0) this.screenLines.push("");
+    this.cursorRow = Math.max(0, this.screenLines.length - 1);
+    this.cursorCol = visibleWidth(this.screenLines[this.cursorRow] ?? "");
+    this.currentLine = "";
+  }
+
+  private ensureScreenLine(row: number): void {
+    while (this.screenLines.length <= row) this.screenLines.push("");
+  }
+
+  private writeScreenChar(char: string): void {
+    this.ensureScreenLine(this.cursorRow);
+    const line = this.screenLines[this.cursorRow] ?? "";
+    const padded = line.length < this.cursorCol ? line + " ".repeat(this.cursorCol - line.length) : line;
+    this.screenLines[this.cursorRow] = padded.slice(0, this.cursorCol) + char + padded.slice(this.cursorCol + 1);
+    this.cursorCol++;
+  }
+
+  private clearScreenLineFromCursor(): void {
+    this.ensureScreenLine(this.cursorRow);
+    this.screenLines[this.cursorRow] = (this.screenLines[this.cursorRow] ?? "").slice(0, this.cursorCol);
+  }
+
+  private flushCurrentLine(): void {
+    if (this.terminalMode) return;
+    this.lines.push(this.currentLine);
+    this.currentLine = "";
+    this.trimBuffer();
+  }
+
+  private trimBuffer(): void {
+    if (this.lines.length > MAX_BUFFER_LINES) this.lines.splice(0, this.lines.length - MAX_BUFFER_LINES);
+    if (this.screenLines.length > MAX_BUFFER_LINES) this.screenLines.splice(0, this.screenLines.length - MAX_BUFFER_LINES);
+  }
+}
+
+export default function spTerminalOverlayExtension(pi: ExtensionAPI): void {
+  pi.registerCommand("sp-feed", {
+    description: "Open a streaming overlay for `sp feed -f`",
+    handler: async (args, ctx) => {
+      await openTerminalOverlay(ctx, "sp feed", resolveSpFeedCommand(args));
+    },
+  });
+
+  pi.registerCommand("sp-ps", {
+    description: "Open a streaming overlay for `sp ps --follow`",
+    handler: async (args, ctx) => {
+      await openTerminalOverlay(ctx, "sp ps", resolveSpPsCommand(args));
+    },
+  });
+
+  pi.registerCommand("xtrm-ps", {
+    description: "Alias for /sp-ps",
+    handler: async (args, ctx) => {
+      await openTerminalOverlay(ctx, "sp ps", resolveSpPsCommand(args));
+    },
+  });
+
+  pi.registerCommand("xtrm-terminal", {
+    description: "Open a streaming terminal overlay for an arbitrary shell command",
+    handler: async (args, ctx) => {
+      const command = args.trim();
+      if (!command) {
+        ctx.ui.notify("Usage: /xtrm-terminal <command>", "warning");
+        return;
+      }
+      await openTerminalOverlay(ctx, command, command);
+    },
+  });
+
+  pi.registerCommand("xtrm-terminal-file", {
+    description: "Open a streaming overlay for a command with one shell-quoted file/path argument",
+    handler: async (args, ctx) => {
+      const [commandName, ...rest] = args.trim().split(/\s+/u);
+      const fileArg = rest.join(" ");
+      if (!commandName || !fileArg) {
+        ctx.ui.notify("Usage: /xtrm-terminal-file <command> <path>", "warning");
+        return;
+      }
+      await openTerminalOverlay(ctx, commandName, `${commandName} ${shellQuote(fileArg)}`);
+    },
+  });
+}

package/extensions/sp-terminal-overlay/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@xtrm/pi-sp-terminal-overlay",
+  "version": "0.1.0",
+  "description": "XTRM Pi overlay for streaming sp feed and terminal command output",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/extensions/xtrm-ui/format.ts

@@ -258,6 +258,9 @@ export function formatLineLabel(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 
+const TOOL_SUMMARY_SUBJECT_MAX = 34;
+const TOOL_SUMMARY_META_MAX = 34;
+
 export function renderToolSummary(
   theme: { fg(color: string, text: string): string; bold(text: string): string },
   status: "pending" | "success" | "error" | "muted",
@@ -270,9 +273,11 @@ export function renderToolSummary(
     : status === "error" ? "error"
     : status === "success" ? "success"
     : "muted";
+  const compactSubject = subject ? shortenCommand(subject, TOOL_SUMMARY_SUBJECT_MAX) : undefined;
+  const compactMeta = meta ? shortenCommand(meta, TOOL_SUMMARY_META_MAX) : undefined;
   let text = `${theme.fg(color, "•")} ${theme.fg("toolTitle", theme.bold(label))}`;
-  if (subject) text += ` ${theme.fg("accent", subject)}`;
-  if (meta) text += theme.fg("muted", ` · ${meta}`);
+  if (compactSubject) text += ` ${theme.fg("accent", compactSubject)}`;
+  if (compactMeta) text += theme.fg("muted", ` · ${compactMeta}`);
   return text;
 }
 

package/extensions/xtrm-ui/index.ts

@@ -32,7 +32,7 @@ import {
   createWriteTool,
 } from "@mariozechner/pi-coding-agent";
 import { Box, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
@@ -57,6 +57,7 @@ import {
 
 export type XtrmThemeName = "pidex-dark" | "pidex-light" | "pidex-dark-flattools" | "pidex-light-flattools";
 export type XtrmDensity = "compact" | "comfortable";
+export type XtrmExternalToolChrome = "background" | "box";
 
 export interface XtrmUiPrefs {
   themeName: XtrmThemeName;
@@ -67,6 +68,7 @@ export interface XtrmUiPrefs {
   forceTheme: boolean; // When false, skip setTheme (allow external theme override)
   toolRowBg: boolean; // Subtle background behind tool text rows (no padding)
   compactExternalToolResults: boolean; // Compact extension tool results (disables full expand output)
+  externalToolChrome: XtrmExternalToolChrome; // Visual treatment for non-native tool rows
   hideThinkingPlaceholder: boolean; // When false, hidden thinking blocks render no placeholder text
 }
 
@@ -85,9 +87,17 @@ export const DEFAULT_PREFS: XtrmUiPrefs = {
   forceTheme: true,
   toolRowBg: false,
   compactExternalToolResults: true,
+  externalToolChrome: "background",
   hideThinkingPlaceholder: false,
 };
 
+let activeExternalToolChrome: XtrmExternalToolChrome = DEFAULT_PREFS.externalToolChrome;
+
+function setActiveExternalToolChrome(chrome: XtrmExternalToolChrome): void {
+  activeExternalToolChrome = chrome;
+}
+
+
 // ============================================================================
 // Preferences
 // ============================================================================
@@ -111,6 +121,7 @@ function normalizePrefs(input: unknown): XtrmUiPrefs {
     toolRowBg: source.toolRowBg ?? DEFAULT_PREFS.toolRowBg,
     compactExternalToolResults:
       source.compactExternalToolResults ?? DEFAULT_PREFS.compactExternalToolResults,
+    externalToolChrome: source.externalToolChrome === "box" ? "box" : "background",
     hideThinkingPlaceholder: source.hideThinkingPlaceholder ?? DEFAULT_PREFS.hideThinkingPlaceholder,
   };
 }
@@ -153,8 +164,39 @@ type PatchableAssistantMessage = {
 
 const PATCHED_ASSISTANT_MESSAGE = "__xtrmUiSilentHiddenThinking";
 
+function maybeFileUrlToPath(value: string): string {
+  return value.startsWith("file:") ? fileURLToPath(value) : value;
+}
+
+function resolvePiCodingAgentEntryPath(): string {
+  const candidates: string[] = [];
+
+  const argvPath = process.argv[1];
+  if (argvPath && existsSync(argvPath)) {
+    const realArgvPath = realpathSync(argvPath);
+    if (realArgvPath.endsWith("/dist/cli.js")) {
+      candidates.push(join(dirname(realArgvPath), "index.js"));
+    }
+  }
+
+  candidates.push(
+    join(dirname(process.execPath), "..", "lib", "node_modules", "@earendil-works", "pi-coding-agent", "dist", "index.js"),
+    join(dirname(process.execPath), "..", "lib", "node_modules", "@mariozechner", "pi-coding-agent", "dist", "index.js"),
+  );
+
+  for (const packageName of ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"]) {
+    try {
+      candidates.push(maybeFileUrlToPath(import.meta.resolve(packageName)));
+    } catch {}
+  }
+
+  const entryPath = candidates.find((candidate) => existsSync(candidate));
+  if (!entryPath) throw new Error("Could not resolve pi-coding-agent entry path");
+  return entryPath;
+}
+
 async function installSilentHiddenThinkingPatch(): Promise<void> {
-  const entryPath = fileURLToPath(import.meta.resolve("@mariozechner/pi-coding-agent"));
+  const entryPath = resolvePiCodingAgentEntryPath();
   const componentPath = join(dirname(entryPath), "modes", "interactive", "components", "assistant-message.js");
   const mod = await import(pathToFileURL(componentPath).href) as {
     AssistantMessageComponent?: AssistantMessageComponentCtor;
@@ -191,6 +233,222 @@ async function installSilentHiddenThinkingPatch(): Promise<void> {
   proto[PATCHED_ASSISTANT_MESSAGE] = true;
 }
 
+type ToolExecutionComponentCtor = {
+  prototype: {
+    getRenderShell?: () => "default" | "self";
+    hasRendererDefinition?: () => boolean;
+    render?: (width: number) => string[];
+  };
+};
+
+type PatchableToolExecutionComponent = {
+  toolName?: string;
+  args?: unknown;
+  result?: { content?: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean };
+  expanded?: boolean;
+  hasRendererDefinition?: () => boolean;
+};
+
+type ExternalToolFrameKind = "serena" | "gitnexus" | "structured" | "process" | "external";
+
+const PATCHED_EXTERNAL_TOOL_FRAME = "__xtrmUiExternalToolFrame";
+const EXTERNAL_TOOL_FRAME_PATCH_VERSION = 11;
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_PATTERN, "");
+}
+
+function isBlankRenderedLine(line: string): boolean {
+  return stripAnsi(line).trim().length === 0;
+}
+
+function externalToolFrameKind(toolName: string | undefined): ExternalToolFrameKind | undefined {
+  if (!toolName || XTRM_BUILTIN_TOOLS.has(toolName)) return undefined;
+  if (toolName === "structured_return") return "structured";
+  if (toolName === "process") return "process";
+  if (toolName.startsWith("gitnexus_")) return "gitnexus";
+  if (SERENA_COMPACT_TOOLS.has(toolName)) return "serena";
+  return "external";
+}
+
+function padVisible(text: string, width: number): string {
+  const visible = visibleWidth(text);
+  return text + " ".repeat(Math.max(0, width - visible));
+}
+
+function getXtrmOriginalText(details: unknown): string | undefined {
+  const record = asRecord(details);
+  return typeof record?.xtrmOriginalText === "string" ? record.xtrmOriginalText : undefined;
+}
+
+function getToolArgs(component: PatchableToolExecutionComponent): Record<string, unknown> {
+  return component.args && typeof component.args === "object" && !Array.isArray(component.args)
+    ? component.args as Record<string, unknown>
+    : {};
+}
+
+function summarizeExternalToolPending(toolName: string | undefined, input: Record<string, unknown>): string {
+  const name = toolName ?? "tool";
+  if (name === "structured_return") {
+    return `• structured_return ${shortenCommand(String(input.command ?? "running"), 38)}`;
+  }
+  if (name === "process") {
+    return `• process ${String(input.action ?? "running")}`;
+  }
+  if (name.startsWith("gitnexus_")) {
+    const subject = summarizeSerenaSubject(name, input) ?? summarizeToolSubject(name, input);
+    return `• ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
+  }
+  if (SERENA_COMPACT_TOOLS.has(name)) {
+    const subject = summarizeSerenaSubject(name, input);
+    return `• serena ${name}${subject ? ` ${subject}` : ""}`;
+  }
+  const subject = summarizeToolSubject(name, input) ?? summarizeSerenaSubject(name, input);
+  return `• ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
+}
+
+function extractResultTextLines(component: PatchableToolExecutionComponent): string[] | undefined {
+  const originalText = component.expanded ? getXtrmOriginalText(component.result?.details) : undefined;
+  if (originalText) return originalText.split("\n");
+
+  const text = component.result?.content?.find((content) => content.type === "text")?.text;
+  if (text) return text.split("\n");
+
+  return [summarizeExternalToolPending(component.toolName, getToolArgs(component))];
+}
+
+function trimRenderedToolLines(lines: string[]): string[] {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && isBlankRenderedLine(lines[start] ?? "")) start++;
+  while (end > start && isBlankRenderedLine(lines[end - 1] ?? "")) end--;
+  return lines.slice(start, end).map((line) => line.replace(/\s+$/u, ""));
+}
+
+function externalToolBadgeColor(kind: ExternalToolFrameKind, text: string): string {
+  const bgColors: Record<ExternalToolFrameKind, [number, number, number]> = {
+    serena: [82, 210, 255],
+    gitnexus: [178, 154, 255],
+    structured: [205, 166, 255],
+    process: [92, 226, 255],
+    external: [178, 190, 210],
+  };
+  const [badgeR, badgeG, badgeB] = bgColors[kind];
+  return `\x1b[38;2;3;8;12m\x1b[48;2;${badgeR};${badgeG};${badgeB}m${text}\x1b[39m\x1b[49m`;
+}
+
+function highlightExternalToolBadge(kind: ExternalToolFrameKind, line: string): string {
+  const match = line.match(/^(•\s+)(\S+)/u);
+  if (!match?.[1] || !match[2]) return line;
+  return match[1] + externalToolBadgeColor(kind, match[2]) + line.slice(match[1].length + match[2].length);
+}
+
+function externalToolBorderColor(kind: ExternalToolFrameKind, text: string): string {
+  const colors: Record<ExternalToolFrameKind, [number, number, number]> = {
+    serena: [150, 210, 255],
+    gitnexus: [185, 168, 255],
+    structured: [205, 166, 255],
+    process: [145, 231, 255],
+    external: [168, 181, 199],
+  };
+  const [r, g, b] = colors[kind];
+  return `[38;2;${r};${g};${b}m${text}`;
+}
+
+function collapsedExternalToolLines(contentLines: string[], expanded: boolean): string[] {
+  return expanded ? contentLines : [contentLines.join(" · ")];
+}
+
+function renderExternalToolBackgroundLines(
+  contentLines: string[],
+  width: number,
+  kind: ExternalToolFrameKind,
+  expanded: boolean,
+): string[] {
+  const availableWidth = Math.max(8, width);
+  const renderWidth = availableWidth;
+  const visibleLines = collapsedExternalToolLines(contentLines, expanded);
+
+  return visibleLines.map((rawLine) => {
+    const line = truncateToWidth(rawLine, Math.max(1, renderWidth));
+    return highlightExternalToolBadge(kind, line);
+  });
+}
+
+function renderExternalToolBoxLines(
+  contentLines: string[],
+  width: number,
+  kind: ExternalToolFrameKind,
+  expanded: boolean,
+): string[] {
+  const availableWidth = Math.max(8, width - 4);
+  const maxContentWidth = expanded ? availableWidth : Math.min(availableWidth, 34);
+  const visibleLines = collapsedExternalToolLines(contentLines, expanded);
+  const contentWidth = Math.max(
+    1,
+    Math.min(maxContentWidth, ...visibleLines.map((line) => visibleWidth(line))),
+  );
+  const innerWidth = contentWidth + 2;
+
+  const framed = [externalToolBorderColor(kind, `╭${"─".repeat(innerWidth)}╮`)];
+  for (const rawLine of visibleLines) {
+    const line = truncateToWidth(rawLine, contentWidth);
+    framed.push(`${externalToolBorderColor(kind, "│")} ${padVisible(line, contentWidth)} ${externalToolBorderColor(kind, "│")}`);
+  }
+  framed.push(externalToolBorderColor(kind, `╰${"─".repeat(innerWidth)}╯`));
+  return framed;
+}
+
+function renderExternalToolLines(
+  lines: string[],
+  width: number,
+  kind: ExternalToolFrameKind,
+  expanded = false,
+): string[] {
+  const contentLines = trimRenderedToolLines(lines).filter((line) => !isBlankRenderedLine(line));
+  if (contentLines.length === 0) return [];
+
+  return activeExternalToolChrome === "box"
+    ? renderExternalToolBoxLines(contentLines, width, kind, expanded)
+    : renderExternalToolBackgroundLines(contentLines, width, kind, expanded);
+}
+
+async function installExternalToolFramePatch(): Promise<void> {
+  const entryPath = resolvePiCodingAgentEntryPath();
+  const componentPath = join(dirname(entryPath), "modes", "interactive", "components", "tool-execution.js");
+  const mod = await import(pathToFileURL(componentPath).href) as {
+    ToolExecutionComponent?: ToolExecutionComponentCtor;
+  };
+  const proto = mod.ToolExecutionComponent?.prototype as
+    | (ToolExecutionComponentCtor["prototype"] & { [PATCHED_EXTERNAL_TOOL_FRAME]?: boolean })
+    | undefined;
+  if (!proto?.render || proto[PATCHED_EXTERNAL_TOOL_FRAME] === EXTERNAL_TOOL_FRAME_PATCH_VERSION) return;
+
+  const getRenderShell = proto.getRenderShell;
+  const render = proto.render;
+
+  proto.getRenderShell = function patchedGetRenderShell(this: PatchableToolExecutionComponent) {
+    const kind = externalToolFrameKind(this.toolName);
+    if (kind) return "self";
+    return getRenderShell?.call(this) ?? "default";
+  };
+
+  proto.render = function patchedRender(this: PatchableToolExecutionComponent, width: number) {
+    const rendered = render.call(this, width);
+    const kind = externalToolFrameKind(this.toolName);
+    if (!kind || rendered.length === 0) return rendered;
+
+    const firstContentIndex = rendered.findIndex((line) => !isBlankRenderedLine(line));
+    const leading = firstContentIndex > 0 ? rendered.slice(0, firstContentIndex) : [];
+    const content = extractResultTextLines(this) ?? rendered;
+    const styled = renderExternalToolLines(content, width, kind, Boolean(this.expanded));
+    return styled.length > 0 ? [...leading, ...styled] : rendered;
+  };
+
+  proto[PATCHED_EXTERNAL_TOOL_FRAME] = EXTERNAL_TOOL_FRAME_PATCH_VERSION;
+}
+
 function applyThinkingChrome(ctx: ExtensionContext, prefs: XtrmUiPrefs): void {
   (ctx.ui as { setHiddenThinkingLabel?: (label?: string) => void }).setHiddenThinkingLabel?.(
     prefs.hideThinkingPlaceholder ? undefined : "",
@@ -396,6 +654,13 @@ function parseDensityArg(arg: string): XtrmDensity | undefined {
   return undefined;
 }
 
+function parseExternalToolChromeArg(arg: string): XtrmExternalToolChrome | undefined {
+  const normalized = arg.trim().toLowerCase();
+  if (normalized === "background" || normalized === "bg" || normalized === "row") return "background";
+  if (normalized === "box" || normalized === "frame" || normalized === "border") return "box";
+  return undefined;
+}
+
 function registerCommands(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs, setPrefs: (p: XtrmUiPrefs) => void, getThinkingLevel: () => string) {
   pi.registerMessageRenderer("xtrm-ui-info", (message, _options, theme) => {
     const title = (message.details as { title?: string } | undefined)?.title ?? "XTRM UI";
@@ -407,7 +672,26 @@ function registerCommands(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs, setPref
 
   pi.registerCommand("xtrm-ui", {
     description: "Show XTRM UI status and active preferences",
-    handler: async (_args, ctx) => {
+    handler: async (args, ctx) => {
+      const trimmedArgs = args.trim();
+      if (trimmedArgs) {
+        const [subcommand, ...rest] = trimmedArgs.split(/\s+/u);
+        if (subcommand === "chrome" || subcommand === "external-chrome" || subcommand === "tool-chrome") {
+          const externalToolChrome = parseExternalToolChromeArg(rest.join(" "));
+          if (!externalToolChrome) {
+            ctx.ui.notify("Usage: /xtrm-ui chrome background|box", "warning");
+            return;
+          }
+          const prefs = { ...getPrefs(), externalToolChrome };
+          setPrefs(prefs);
+          persistPrefs(pi, prefs);
+          ctx.ui.notify(`External tool chrome set to ${externalToolChrome}.`, "info");
+          return;
+        }
+        ctx.ui.notify("Usage: /xtrm-ui [chrome background|box]", "warning");
+        return;
+      }
+
       const prefs = getPrefs();
       const contextUsage = ctx.getContextUsage();
       const lines = [
@@ -419,6 +703,7 @@ function registerCommands(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs, setPref
         `Show footer: ${prefs.showFooter ? "yes" : "no"} (custom-footer handles this)`,
         `Tool row background: ${prefs.toolRowBg ? "on" : "off"}`,
         `Compact external tool results: ${prefs.compactExternalToolResults ? "on" : "off"}`,
+        `External tool chrome: ${prefs.externalToolChrome}`,
         `Model: ${ctx.model?.id ?? "none"}`,
         `Context: ${contextUsage?.tokens ?? "unknown"}/${contextUsage?.contextWindow ?? "unknown"}`,
       ];
@@ -549,6 +834,25 @@ function registerCommands(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs, setPref
     },
   });
 
+  pi.registerCommand("xtrm-ui-external-chrome", {
+    description: "Choose non-native tool chrome: background|box",
+    getArgumentCompletions: (prefix) => {
+      const values = ["background", "box"].filter((item) => item.startsWith(prefix));
+      return values.length > 0 ? values.map((value) => ({ value, label: value })) : null;
+    },
+    handler: async (args, ctx) => {
+      const externalToolChrome = parseExternalToolChromeArg(args);
+      if (!externalToolChrome) {
+        ctx.ui.notify("Usage: /xtrm-ui-external-chrome background|box", "warning");
+        return;
+      }
+      const prefs = { ...getPrefs(), externalToolChrome };
+      setPrefs(prefs);
+      persistPrefs(pi, prefs);
+      ctx.ui.notify(`External tool chrome set to ${externalToolChrome}.`, "info");
+    },
+  });
+
   pi.registerCommand("xtrm-ui-reset", {
     description: "Restore XTRM UI defaults",
     handler: async (_args, ctx) => {
@@ -956,6 +1260,101 @@ function summarizeGenericToolResult(
   return `• ${normalized}${subject ? ` ${subject}` : ""}${joined ? ` · ${joined}` : ""}`;
 }
 
+function summarizeStructuredReturnToolResult(
+  input: Record<string, unknown>,
+  text: string,
+  details: unknown,
+  durationMs: number | undefined,
+): string {
+  const record = asRecord(details);
+  const command = shortenCommand(String(input.command ?? text.split("→")[0] ?? "command"), 52);
+  const resultText = text.includes("→") ? text.split("→").slice(1).join("→").trim() : text.trim();
+  const resultLines = resultText.split("\n").map((line) => line.trim()).filter(Boolean);
+  const summary = resultLines.find((line) => !line.startsWith("cwd:"));
+  const parser = typeof record?.parser === "string" ? record.parser : undefined;
+  const exitCode = typeof record?.exitCode === "number" ? `exit ${record.exitCode}` : undefined;
+  const duration = formatDuration(durationMs);
+  const meta = joinMeta([summary ? shortenCommand(summary, 72) : undefined, parser, exitCode, duration]);
+  return `• structured_return ${command}${meta ? ` · ${meta}` : ""}`;
+}
+
+function summarizeProcessToolResult(
+  input: Record<string, unknown>,
+  text: string,
+  details: unknown,
+  durationMs: number | undefined,
+): string {
+  const record = asRecord(details);
+  const action = String(record?.action ?? input.action ?? "action");
+  const duration = formatDuration(durationMs);
+  const meta = (...parts: Array<string | undefined>) => {
+    const joined = joinMeta([...parts, duration]);
+    return joined ? ` · ${joined}` : "";
+  };
+
+  if (action === "start") {
+    const proc = asRecord(record?.process);
+    const name = String(proc?.name ?? input.name ?? "process");
+    const id = proc?.id ? String(proc.id) : undefined;
+    const pid = proc?.pid != null ? `pid ${String(proc.pid)}` : undefined;
+    return `• process start "${name}"${meta(id, pid)}`;
+  }
+
+  if (action === "list") {
+    const processes = Array.isArray(record?.processes) ? record.processes : [];
+    const running = processes.filter((item) => {
+      const proc = asRecord(item);
+      return proc?.status === "running" || proc?.status === "terminating";
+    }).length;
+    return `• process list${meta(`${processes.length} ${processes.length === 1 ? "process" : "processes"}`, `${running} running`)}`;
+  }
+
+  if (action === "output") {
+    const output = asRecord(record?.output);
+    const stdout = Array.isArray(output?.stdout) ? output.stdout.length : undefined;
+    const stderr = Array.isArray(output?.stderr) ? output.stderr.length : undefined;
+    return `• process output ${String(input.id ?? "process")}${meta(
+      stdout != null ? `${stdout} stdout` : undefined,
+      stderr != null ? `${stderr} stderr` : undefined,
+    )}`;
+  }
+
+  if (action === "logs") {
+    return `• process logs ${String(input.id ?? "process")}${meta("log paths")}`;
+  }
+
+  const message = typeof record?.message === "string" ? record.message : text.split("\n")[0];
+  return `• process ${action}${message ? ` · ${shortenCommand(message, 38)}` : ""}${duration ? ` · ${duration}` : ""}`;
+}
+
+function summarizeExternalToolResult(
+  toolName: string,
+  input: Record<string, unknown>,
+  text: string,
+  details: unknown,
+  durationMs: number | undefined,
+): string {
+  if (SERENA_COMPACT_TOOLS.has(toolName)) {
+    return summarizeSerenaToolResult(toolName, input, text, durationMs);
+  }
+  if (toolName === "structured_return") {
+    return summarizeStructuredReturnToolResult(input, text, details, durationMs);
+  }
+  if (toolName === "process") {
+    return summarizeProcessToolResult(input, text, details, durationMs);
+  }
+  return summarizeGenericToolResult(toolName, input, text, durationMs);
+}
+
+function withXtrmToolDetails(details: unknown, sourceText: string, toolName: string): unknown {
+  const record = asRecord(details);
+  return {
+    ...(record ?? {}),
+    xtrmOriginalText: sourceText,
+    xtrmToolFrame: externalToolFrameKind(toolName),
+  };
+}
+
 const XTRM_BUILTIN_TOOLS = new Set(["bash", "read", "edit", "write", "find", "grep", "ls"]);
 
 function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): void {
@@ -1004,7 +1403,11 @@ function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): voi
 
   pi.on("tool_result", async (event: ToolResultEvent, _ctx) => {
     if (event.isError) return undefined;
-    if (XTRM_BUILTIN_TOOLS.has(event.toolName)) return undefined;
+    if (XTRM_BUILTIN_TOOLS.has(event.toolName)) {
+      trackToolCallEnd(event.toolCallId);
+      return undefined;
+    }
+    if (!getPrefs().compactExternalToolResults) return undefined;
 
     const text = getTextContent({ content: event.content as Array<{ type: string; text?: string }> });
     const startedAt = toolCallStartTimes.get(event.toolCallId);
@@ -1018,13 +1421,17 @@ function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): voi
         ? (event.input as Record<string, unknown>)
         : {};
 
-    const compactText = SERENA_COMPACT_TOOLS.has(event.toolName)
-      ? summarizeSerenaToolResult(event.toolName, safeInput, sourceText, durationMs)
-      : summarizeGenericToolResult(event.toolName, safeInput, sourceText, durationMs);
+    const compactText = summarizeExternalToolResult(
+      event.toolName,
+      safeInput,
+      sourceText,
+      event.details,
+      durationMs,
+    );
 
     return {
       content: [{ type: "text", text: formatHierarchyText(compactText) }],
-      details: event.details,
+      details: withXtrmToolDetails(event.details, sourceText, event.toolName),
     };
   });
 
@@ -1043,7 +1450,7 @@ function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): voi
     renderResult(result, { expanded, isPartial }, theme) {
       const details = (result.details ?? {}) as DetailsWithXtrmMeta<BashToolDetails, Record<string, unknown>>;
       const meta = getXtrmMeta<BashToolDetails, Record<string, unknown>>(details);
-      const command = shortenCommand(String(meta?.args.command ?? ""));
+      const command = shortenCommand(String(meta?.args.command ?? ""), 38);
       if (isPartial) {
         return toolRowText(theme, `${theme.fg("accent", "•")} ${theme.fg("toolTitle", "Running ")}${theme.fg("accent", command)}${theme.fg("toolTitle", " in bash")}`);
       }
@@ -1263,13 +1670,17 @@ function isXtrmTheme(name: string | undefined): boolean {
 
 export default function xtrmUiExtension(pi: ExtensionAPI): void {
   void installSilentHiddenThinkingPatch().catch(() => undefined);
+  void installExternalToolFramePatch().catch(() => undefined);
 
   let prefs: XtrmUiPrefs = { ...DEFAULT_PREFS };
   let previousThemeName: string | null = null;
   const extensionThemeDir = join(__dirname, "../../themes/xtrm-ui");
 
   const getPrefs = () => prefs;
-  const setPrefs = (p: XtrmUiPrefs) => { prefs = p; };
+  const setPrefs = (p: XtrmUiPrefs) => {
+    prefs = p;
+    setActiveExternalToolChrome(p.externalToolChrome);
+  };
   const getThinkingLevel = () => formatThinking(pi.getThinkingLevel());
 
   registerXtrmUiTools(pi, getPrefs);
@@ -1285,7 +1696,7 @@ export default function xtrmUiExtension(pi: ExtensionAPI): void {
   }));
 
   pi.on("session_start", async (_event, ctx) => {
-    prefs = loadPrefs(ctx.sessionManager.getEntries() as Array<MaybeCustomEntry>);
+    setPrefs(loadPrefs(ctx.sessionManager.getEntries() as Array<MaybeCustomEntry>));
     if (!previousThemeName && !isXtrmTheme(ctx.ui.theme.name)) {
       previousThemeName = ctx.ui.theme.name ?? null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/pi-extensions",
-  "version": "0.7.17",
+  "version": "0.7.21",
   "description": "Unified Pi extension entrypoint for xtrm-managed extensions",
   "type": "module",
   "publishConfig": {

package/src/extensions/sp-terminal-overlay.ts

@@ -0,0 +1,3 @@
+import registerExtension from "../../extensions/sp-terminal-overlay/index.ts";
+
+export default registerExtension;

package/src/registry.ts

@@ -12,6 +12,7 @@ import piSerenaCompactExtension from "./extensions/pi-serena-compact.ts";
 import qualityGatesExtension from "./extensions/quality-gates.ts";
 import serviceSkillsExtension from "./extensions/service-skills.ts";
 import sessionFlowExtension from "./extensions/session-flow.ts";
+import spTerminalOverlayExtension from "./extensions/sp-terminal-overlay.ts";
 import xtrmLoaderExtension from "./extensions/xtrm-loader.ts";
 import xtrmUiExtension from "./extensions/xtrm-ui.ts";
 
@@ -33,6 +34,7 @@ export const managedPiExtensions: readonly ManagedPiExtension[] = [
   { id: "quality-gates", register: qualityGatesExtension },
   { id: "service-skills", register: serviceSkillsExtension },
   { id: "session-flow", register: sessionFlowExtension },
+  { id: "sp-terminal-overlay", register: spTerminalOverlayExtension },
   { id: "xtrm-loader", register: xtrmLoaderExtension },
   { id: "xtrm-ui", register: xtrmUiExtension },
 ];