@saifymatteo/pi-extensions 0.0.0-stage → 0.1.0

package/packages/pi-session-nav/README.md

@@ -0,0 +1,32 @@
+# pi-session-nav
+
+Navigate visible user and assistant messages on the active conversation branch without adding transcript entries.
+
+## Running locally
+
+From the monorepo root:
+
+```sh
+pi -e ./packages/pi-session-nav
+```
+
+**Warning:** this extension uses your existing Pi resources and settings unless you load it in an isolated home (see the root README). Do not load two copies of the same extension (for example an older standalone file alongside this package): commands and hooks can duplicate. The package never installs or relocates personal settings.
+
+## Commands and shortcuts
+
+- `/session-nav` or `Alt+O` — opens the navigator.
+- Up/Down to select, Enter to jump, Escape/Ctrl+C to cancel.
+
+## Settings and storage
+
+No settings file. The last selected message ID is kept in module memory only. Compacted-away and textless/tool-only messages are excluded.
+
+## Privacy and operations
+
+Reads the in-memory branch and rendered transcript; does not write files, send model requests or change the branch.
+
+## Compatibility
+
+Node.js >=24 for development checks; run extensions through Pi's TypeScript loader. Host imports are wildcard peers, not bundled runtime copies. Jumping relies on Pi's fullscreen TUI internal layout/component properties, not a stable public scrolling API. Regular terminal mode can open the dialog but cannot jump; a warning is shown. Runtime upgrades may break message matching or scrolling.
+
+See [NOTICE.md](NOTICE.md) for provenance. Tests use the monorepo's TypeScript dev dependency and VM loader; they do not contact services or write to user-home resources.

package/packages/pi-session-nav/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saifymatteo/pi-session-nav",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "description": "Jump between messages in the active context (compaction-aware).",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-session-nav"
+  }
+}

package/packages/pi-session-nav/src/index.ts

@@ -0,0 +1,203 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type Component, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { DIALOG_OVERLAY, dialogRows, wheelAsArrows } from "./lib/dialog.ts";
+
+type Entry = { id: string; type: string; firstKeptEntryId?: string; message?: { role?: string; content?: unknown; timestamp?: number } };
+type NavItem = { id: string; role: string; preview: string; timestamp: number; available: boolean };
+
+let lastSelectedId: string | null = null;
+
+function cleanText(value: unknown): string {
+	const blocks = typeof value === "string" ? [{ type: "text", text: value }] : Array.isArray(value) ? value : [];
+	return blocks.flatMap((block: any) => block?.type === "text" && typeof block.text === "string" ? [block.text] : block?.type === "image" ? ["[image]"] : [])
+		.join(" ").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export function activeContextIds(branch: Entry[]): Set<string> {
+	const latestCompactionIndex = branch.reduce((latest, entry, index) => entry.type === "compaction" ? index : latest, -1);
+	if (latestCompactionIndex < 0) return new Set(branch.map((entry) => entry.id));
+	const compaction = branch[latestCompactionIndex];
+	const keptIndex = branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+	const ids = new Set<string>([compaction.id]);
+	if (keptIndex >= 0 && keptIndex < latestCompactionIndex) {
+		for (const entry of branch.slice(keptIndex, latestCompactionIndex)) ids.add(entry.id);
+	}
+	for (const entry of branch.slice(latestCompactionIndex + 1)) ids.add(entry.id);
+	return ids;
+}
+
+export function buildNavigationItems(branch: Entry[], activeIds: Set<string>): NavItem[] {
+	return branch.flatMap((entry) => {
+		if (entry.type !== "message" || (entry.message?.role !== "user" && entry.message?.role !== "assistant")) return [];
+		const preview = cleanText(entry.message.content);
+		// Assistant messages with no visible text are usually tool-call-only messages.
+		if (!preview || !activeIds.has(entry.id)) return [];
+		return [{ id: entry.id, role: entry.message.role, preview, timestamp: entry.message.timestamp ?? 0, available: true }];
+	});
+}
+
+export function visibleRange(selected: number, itemCount: number, pageSize: number): number {
+	return Math.max(0, Math.min(selected - pageSize + 1, itemCount - pageSize));
+}
+
+function normalizeForMatch(value: unknown): string {
+	return cleanText(value).normalize("NFKC").toLocaleLowerCase();
+}
+
+function visibleMessageText(message: any): string {
+	return cleanText(message?.content);
+}
+
+function walkComponents(root: any, out: any[] = [], seen = new Set<any>()): any[] {
+	if (!root || seen.has(root)) return out;
+	seen.add(root);
+	out.push(root);
+	for (const child of root.children ?? []) walkComponents(child, out, seen);
+	if (root.child && root.child !== root) walkComponents(root.child, out, seen);
+	return out;
+}
+
+function jumpToMessage(tui: any, item: NavItem, targetMessage: any, items: NavItem[]): boolean {
+	try {
+		if (tui?.mode !== "fullscreen") return false;
+		const layout = tui.currentLayout?.primaryScrollView;
+		const scroll = layout?.primary && typeof layout.scrollTo === "function" ? layout : walkComponents(tui.layoutRoot).find((component) => component.primary && typeof component.scrollTo === "function");
+		const doc = scroll?.child;
+		if (!scroll || !doc) return false;
+		const components = walkComponents(doc);
+		const targetText = normalizeForMatch(visibleMessageText(targetMessage));
+		const candidates = components.filter((component) => item.role === "user"
+			? typeof component.text === "string" && typeof component.rebuild === "function"
+			: component.lastMessage?.role === "assistant");
+		const matching = candidates.filter((component) => normalizeForMatch(item.role === "user" ? component.text : visibleMessageText(component.lastMessage)) === targetText);
+		const itemIndex = items.findIndex((candidate) => candidate.id === item.id);
+		if (itemIndex < 0) return false;
+		const occurrence = items.slice(0, itemIndex)
+			.filter((candidate) => candidate.role === item.role && normalizeForMatch(candidate.preview) === targetText).length;
+		const target = matching[occurrence];
+		if (!target) return false;
+		const width = Math.max(1, scroll.getContentWidth(tui.terminal?.columns ?? 80));
+		const stripAnsi = (line: string) => line.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "");
+		const targetLines = target.render(width).map((line: string) => stripAnsi(line));
+		const firstRenderedLine = targetLines.find((line: string) => line.trim().length > 0);
+		if (!firstRenderedLine) return false;
+		const sameBefore = candidates.slice(0, candidates.indexOf(target))
+			.filter((component) => component.render(width).some((line: string) => stripAnsi(line) === firstRenderedLine)).length;
+		const docLines: string[] = doc.render(width);
+		let occurrenceInDocument = 0;
+		let offset = -1;
+		for (let index = 0; index < docLines.length; index++) {
+			if (stripAnsi(docLines[index]) === firstRenderedLine && occurrenceInDocument++ === sameBefore) {
+				offset = index;
+				break;
+			}
+		}
+		if (offset < 0) return false;
+		scroll.scrollTo(offset, { disableFollow: true });
+		tui.requestRender?.();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+class Navigator implements Component {
+	private selected: number;
+	private offset: number;
+	// Fixed lines: 2 borders, 2 blank spacers, footer.
+	private get pageSize(): number { return dialogRows(this.tui, 5); }
+
+	constructor(private readonly tui: any, private readonly items: NavItem[], private readonly done: (id: string | null) => void, private readonly theme: any, initialIndex: number) {
+		this.selected = Math.max(0, Math.min(initialIndex, items.length - 1));
+		this.offset = visibleRange(this.selected, items.length, this.pageSize);
+	}
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const border = (text: string) => this.theme.fg("border", text);
+		const inner = Math.max(1, width - 2);
+		const contentWidth = Math.max(1, inner - 2);
+		const title = ` Navigate conversation · ${this.items.length} messages `;
+		const topTitle = truncateToWidth(title, Math.max(1, inner - 1), "…");
+		const lines = [border(`┏${topTitle}${"━".repeat(Math.max(0, inner - visibleWidth(topTitle)))}┓`)];
+		const messageRow = (text: string, role: "user" | "assistant", selected: boolean) => {
+			const fitted = truncateToWidth(text, contentWidth, "…");
+			const padded = ` ${fitted}${" ".repeat(Math.max(0, contentWidth - visibleWidth(fitted)))} `;
+			const styledText = role === "user"
+				? this.theme.bg("userMessageBg", this.theme.fg(selected ? "warning" : "userMessageText", padded))
+			: this.theme.fg(selected ? "warning" : "dim", padded);
+			return border("┃") + styledText + border("┃");
+		};
+		const plainRow = (text: string) => {
+			const fitted = truncateToWidth(text, contentWidth, "…");
+			return border("┃") + ` ${fitted}${" ".repeat(Math.max(0, contentWidth - visibleWidth(fitted)))} ` + border("┃");
+		};
+		lines.push(plainRow(""));
+		const list = this.items.slice(this.offset, this.offset + this.pageSize);
+		for (let index = 0; index < this.pageSize; index++) {
+			const item = list[index];
+			const isSelected = this.offset + index === this.selected;
+			if (!item) {
+				lines.push(plainRow(""));
+				continue;
+			}
+			const prefix = isSelected ? "▶ " : "  ";
+			const isLatest = this.offset + index === this.items.length - 1;
+			const row = `${prefix}${item.role === "user" ? "You" : "Pi"}${isLatest ? " · latest" : ""}: ${item.preview}`;
+			lines.push(messageRow(row, item.role as "user" | "assistant", isSelected));
+		}
+		lines.push(plainRow(""));
+		lines.push(plainRow(this.theme.fg("dim", `↑↓ navigate · ${this.selected + 1}/${this.items.length} · Enter jump · Esc close`)));
+		lines.push(border(`┗${"━".repeat(inner)}┛`));
+		return lines;
+	}
+
+	handleMouse(event: TuiMouseEvent) { return wheelAsArrows(event, (key) => this.handleInput(key)); }
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) return this.done(null);
+		if (matchesKey(data, "up")) this.selected = Math.max(0, this.selected - 1);
+		else if (matchesKey(data, "down")) this.selected = Math.min(this.items.length - 1, this.selected + 1);
+		else if (matchesKey(data, "enter")) {
+			const item = this.items[this.selected];
+			if (item) {
+				lastSelectedId = item.id;
+				this.done(item.available ? item.id : `hidden:${item.id}`);
+			}
+		}
+		this.offset = visibleRange(this.selected, this.items.length, this.pageSize);
+		this.tui.requestRender();
+	}
+}
+
+export default function (pi: ExtensionAPI): void {
+	async function open(ctx: any): Promise<void> {
+		const sessionManager = ctx.sessionManager;
+		const entries = sessionManager.getEntries() as Entry[];
+		const branch = sessionManager.getBranch() as Entry[];
+		let activeIds: Set<string>;
+		try {
+			const contextEntries = typeof sessionManager.buildContextEntries === "function" ? sessionManager.buildContextEntries() : undefined;
+			activeIds = Array.isArray(contextEntries) ? new Set(contextEntries.map((entry: Entry) => entry.id)) : activeContextIds(branch);
+		} catch {
+			activeIds = activeContextIds(branch);
+		}
+		const items = buildNavigationItems(branch, activeIds);
+		if (!items.length) return ctx.ui.notify("No user or assistant messages in this session", "info");
+		const previousIndex = lastSelectedId ? items.findIndex((item) => item.id === lastSelectedId) : -1;
+		const initialIndex = previousIndex >= 0 ? previousIndex : items.length - 1;
+		let tuiRef: any;
+		const selected: string | null = await ctx.ui.custom((tui, theme, _keybindings, done) => {
+			tuiRef = tui;
+			return new Navigator(tui, items, done, theme, initialIndex);
+		}, DIALOG_OVERLAY);
+		if (selected === null) return;
+		if (selected.startsWith("hidden:")) return ctx.ui.notify("That message is hidden by compaction and cannot be jumped to", "warning");
+		const item = items.find((candidate) => candidate.id === selected);
+		const entry = entries.find((candidate) => candidate.id === selected);
+		if (!item?.available || !entry || entry.type !== "message") return ctx.ui.notify("Message is no longer available in this session", "warning");
+		if (!jumpToMessage(tuiRef, item, entry.message, items)) ctx.ui.notify("Could not locate that message in the visible transcript", "warning");
+	}
+	pi.registerCommand("session-nav", { description: "Navigate to a message in the current conversation", handler: async (_args, ctx) => open(ctx) });
+	pi.registerShortcut(Key.alt("o"), { description: "Navigate conversation", handler: async (ctx) => open(ctx) });
+}

package/packages/pi-session-nav/src/lib/dialog.ts

@@ -0,0 +1,31 @@
+// One size for every overlay dialog in this package. Change DIALOG_HEIGHT here and every dialog follows:
+// the overlay is capped at that share of the terminal and each dialog pads its list to fill it.
+
+/** Share of the terminal height every dialog fills. */
+export const DIALOG_HEIGHT = 0.8
+
+/** `ctx.ui.custom(factory, DIALOG_OVERLAY)`: centered, 92% wide, DIALOG_HEIGHT tall. */
+export const DIALOG_OVERLAY = {
+  overlay: true,
+  overlayOptions: { anchor: 'center', width: '92%', maxHeight: `${DIALOG_HEIGHT * 100}%`, margin: 1 },
+} as const
+
+/**
+ * Scrolling rows that fit once `chrome` fixed lines (borders, search, header, footer) are drawn.
+ * Same floor as the overlay's own percentage, so dialog and overlay agree; read it in render() so a
+ * resize takes effect on the next frame.
+ */
+export const dialogRows = (tui: { terminal?: { rows: number } }, chrome: number, min = 1): number =>
+  Math.max(min, Math.floor((tui.terminal?.rows ?? 24) * DIALOG_HEIGHT) - chrome)
+
+/**
+ * Mouse wheel → ↑/↓ key presses, so a dialog reuses its own keyboard handling (clamping, render).
+ * Use as `handleMouse(e) { return wheelAsArrows(e, (k) => this.handleInput(k)) }`. Fullscreen mode only:
+ * regular mode leaves the mouse to the terminal. Handling the wheel also stops it scrolling the transcript behind.
+ */
+export function wheelAsArrows(event: { type: string; wheelDelta?: number }, handleInput: (data: string) => void): { handled: true } | undefined {
+  if (event.type !== 'wheel' || !event.wheelDelta) return undefined
+  const key = event.wheelDelta < 0 ? '\x1b[A' : '\x1b[B'
+  for (let i = 0; i < Math.min(Math.abs(event.wheelDelta), 20); i++) handleInput(key)
+  return { handled: true }
+}

package/packages/pi-session-nav/test/behavior.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { loadExtension } from '../../../test/load-extension.mjs';
+const { activeContextIds, buildNavigationItems, visibleRange } = loadExtension(new URL('../src/index.ts', import.meta.url), {
+  '@earendil-works/pi-tui': {},
+});
+const message = (id, role, content) => ({ id, type: 'message', message: { role, content, timestamp: 42 } });
+
+test('latest compaction keeps its retained prefix and subsequent branch only', () => {
+  const branch = [message('old', 'user', 'old'), message('kept', 'user', 'kept'),
+    { id: 'c1', type: 'compaction', firstKeptEntryId: 'kept' }, message('new', 'assistant', 'new')];
+  assert.deepEqual([...activeContextIds(branch)], ['c1', 'kept', 'new']);
+  const latest = [...branch, { id: 'c2', type: 'compaction', firstKeptEntryId: 'new' }, message('last', 'user', 'last')];
+  assert.deepEqual([...activeContextIds(latest)], ['c2', 'new', 'last']);
+  assert.deepEqual([...activeContextIds([{ id: 'c', type: 'compaction', firstKeptEntryId: 'missing' }, latest.at(-1)])], ['c', 'last']);
+  assert.deepEqual([...activeContextIds(branch.slice(0, 2))], ['old', 'kept']);
+});
+
+test('navigation excludes inactive, tool, metadata, and textless messages; cleans previews', () => {
+  const branch = [message('hidden', 'user', 'hidden'), message('user', 'user', [{ type: 'text', text: '  hello\n world\x1b ' }, { type: 'image' }]),
+    message('tool', 'toolResult', 'result'), message('silent', 'assistant', [{ type: 'toolCall', name: 'read' }]),
+    message('assistant', 'assistant', 'reply'), { id: 'custom', type: 'custom' }];
+  const items = JSON.parse(JSON.stringify(buildNavigationItems(branch, new Set(branch.slice(1).map(x => x.id)))));
+  assert.deepEqual(items, [
+    { id: 'user', role: 'user', preview: 'hello world [image]', timestamp: 42, available: true },
+    { id: 'assistant', role: 'assistant', preview: 'reply', timestamp: 42, available: true },
+  ]);
+});
+
+test('visible window offset clamps at both edges including short and empty lists', () => {
+  assert.equal(visibleRange(0, 20, 5), 0);
+  assert.equal(visibleRange(7, 20, 5), 3);
+  assert.equal(visibleRange(50, 20, 5), 15);
+  assert.equal(visibleRange(2, 3, 10), 0);
+  assert.equal(visibleRange(0, 0, 10), 0);
+});