@maxiaochao/pi-toolkit 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2026-09-03 - v0.2.2
+
+- let the focused `/btw` overlay scroll its full transcript with Up/Down and PageUp/PageDown
+
+## 2026-09-02 - v0.2.1
+
+- update global agent instructions for harness-native file editing
+- remove the HTML artifact output preference from the global instructions
+
 ## 2026-09-02 - v0.2.0
 
 - bundle the Apache-2.0 `web-browser` skill for Chrome/Chromium CDP automation

package/README.md

@@ -38,7 +38,7 @@ To synchronize the file directly from a checkout instead:
 bash scripts/install.sh
 ```
 
-The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly.
+The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly. While the BTW overlay has focus, use `Up` / `Down` to scroll its transcript one line at a time and `PageUp` / `PageDown` to move by one transcript page.
 
 The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
 

package/extensions/btw-scroll.ts

@@ -0,0 +1,9 @@
+export function getBtwPageScrollSize(viewportHeight: number): number {
+	return Math.max(1, Math.floor(viewportHeight));
+}
+
+export function clampBtwScrollTop(scrollTop: number, contentHeight: number, viewportHeight: number): number {
+	const maxScrollTop = Math.max(0, Math.floor(contentHeight) - Math.floor(viewportHeight));
+	const requested = Number.isFinite(scrollTop) ? Math.trunc(scrollTop) : 0;
+	return Math.max(0, Math.min(maxScrollTop, requested));
+}

package/extensions/btw.ts

@@ -23,6 +23,7 @@ import {
 	type OverlayHandle,
 	type TUI,
 } from "@earendil-works/pi-tui";
+import { clampBtwScrollTop, getBtwPageScrollSize } from "./btw-scroll.ts";
 
 const BTW_ENTRY_TYPE = "btw-thread-entry";
 const BTW_RESET_TYPE = "btw-thread-reset";
@@ -59,6 +60,7 @@ type OverlayRuntime = {
 	close?: () => void;
 	finish?: () => void;
 	setDraft?: (value: string) => void;
+	scrollToEnd?: () => void;
 	closed?: boolean;
 };
 
@@ -201,6 +203,10 @@ class BtwOverlay extends Container implements Focusable {
 	private readonly getStatus: () => string;
 	private readonly onSubmitCallback: (value: string) => void;
 	private readonly onDismissCallback: () => void;
+	private transcriptScrollTop = 0;
+	private transcriptFollowingEnd = true;
+	private transcriptContentHeight = 0;
+	private transcriptViewportHeight = 0;
 	private _focused = false;
 
 	get focused(): boolean {
@@ -245,9 +251,65 @@ class BtwOverlay extends Container implements Focusable {
 			return;
 		}
 
+		if (this.keybindings.matches(data, "tui.select.up")) {
+			this.scrollTranscriptBy(-1);
+			return;
+		}
+
+		if (this.keybindings.matches(data, "tui.select.down")) {
+			this.scrollTranscriptBy(1);
+			return;
+		}
+
+		const pageSize = getBtwPageScrollSize(this.transcriptViewportHeight);
+		if (this.keybindings.matches(data, "tui.select.pageUp")) {
+			this.scrollTranscriptBy(-pageSize);
+			return;
+		}
+
+		if (this.keybindings.matches(data, "tui.select.pageDown")) {
+			this.scrollTranscriptBy(pageSize);
+			return;
+		}
+
 		this.input.handleInput(data);
 	}
 
+	private scrollTranscriptBy(lines: number): void {
+		const maxScrollTop = Math.max(0, this.transcriptContentHeight - this.transcriptViewportHeight);
+		const currentScrollTop = this.transcriptFollowingEnd
+			? maxScrollTop
+			: clampBtwScrollTop(this.transcriptScrollTop, this.transcriptContentHeight, this.transcriptViewportHeight);
+		const nextScrollTop = clampBtwScrollTop(
+			currentScrollTop + Math.trunc(lines),
+			this.transcriptContentHeight,
+			this.transcriptViewportHeight,
+		);
+		const nextFollowingEnd = nextScrollTop === maxScrollTop;
+		if (nextScrollTop === currentScrollTop && nextFollowingEnd === this.transcriptFollowingEnd) {
+			return;
+		}
+
+		this.transcriptScrollTop = nextScrollTop;
+		this.transcriptFollowingEnd = nextFollowingEnd;
+		this.tui.requestRender();
+	}
+
+	scrollTranscriptToEnd(): void {
+		const nextScrollTop = clampBtwScrollTop(
+			this.transcriptContentHeight,
+			this.transcriptContentHeight,
+			this.transcriptViewportHeight,
+		);
+		if (this.transcriptFollowingEnd && this.transcriptScrollTop === nextScrollTop) {
+			return;
+		}
+
+		this.transcriptScrollTop = nextScrollTop;
+		this.transcriptFollowingEnd = true;
+		this.tui.requestRender();
+	}
+
 	setDraft(value: string): void {
 		this.input.setValue(value);
 		this.tui.requestRender();
@@ -279,7 +341,19 @@ class BtwOverlay extends Container implements Focusable {
 
 		// Markdown renders to innerWidth already — no manual wrapping needed
 		const transcript = this.getTranscript(innerWidth, this.theme);
-		const visibleTranscript = transcript.slice(-transcriptHeight);
+		this.transcriptContentHeight = transcript.length;
+		this.transcriptViewportHeight = transcriptHeight;
+		const maxScrollTop = Math.max(0, this.transcriptContentHeight - this.transcriptViewportHeight);
+		if (this.transcriptFollowingEnd) {
+			this.transcriptScrollTop = maxScrollTop;
+		} else {
+			this.transcriptScrollTop = clampBtwScrollTop(
+				this.transcriptScrollTop,
+				this.transcriptContentHeight,
+				this.transcriptViewportHeight,
+			);
+		}
+		const visibleTranscript = transcript.slice(this.transcriptScrollTop, this.transcriptScrollTop + transcriptHeight);
 		const transcriptPadding = Math.max(0, transcriptHeight - visibleTranscript.length);
 
 		const status = this.getStatus();
@@ -308,7 +382,7 @@ class BtwOverlay extends Container implements Focusable {
 		lines.push(
 			`${this.theme.fg("borderMuted", "│")}${inputLine}${this.theme.fg("borderMuted", "│")}`,
 		);
-		lines.push(this.frameLine(this.theme.fg("dim", "Enter submit · Esc close"), innerWidth));
+		lines.push(this.frameLine(this.theme.fg("dim", "↑/↓ scroll · PgUp/PgDn page · Enter submit · Esc close"), innerWidth));
 		lines.push(this.borderLine(innerWidth, "bottom"));
 
 		return lines;
@@ -396,7 +470,7 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		const lines: string[] = [];
-		for (const item of thread.slice(-6)) {
+		for (const item of thread) {
 			// User message
 			const userText = item.question.trim().split("\n")[0];
 			lines.push(theme.fg("accent", theme.bold("You: ")) + truncateToWidth(userText, width - 5, "…"));
@@ -509,6 +583,7 @@ export default function (pi: ExtensionAPI) {
 		setOverlayDraft("");
 		setOverlayStatus("Ready");
 		await disposeSideSession();
+		overlayRuntime?.scrollToEnd?.();
 		if (persist) {
 			const details: BtwResetDetails = { timestamp: Date.now() };
 			pi.appendEntry(BTW_RESET_TYPE, details);
@@ -546,6 +621,7 @@ export default function (pi: ExtensionAPI) {
 			thread.push(details);
 		}
 
+		overlayRuntime?.scrollToEnd?.();
 		syncOverlay();
 	}
 
@@ -691,6 +767,7 @@ export default function (pi: ExtensionAPI) {
 					overlay.focused = true;
 					overlay.setDraft(overlayDraft);
 					runtime.setDraft = (value) => overlay.setDraft(value);
+					runtime.scrollToEnd = () => overlay.scrollTranscriptToEnd();
 					runtime.refresh = () => {
 						overlay.focused = runtime.handle?.isFocused() ?? false;
 						tui.requestRender();
@@ -836,6 +913,7 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		overlayRuntime?.scrollToEnd?.();
 		const side = await ensureSideSession(ctx);
 		if (!side) {
 			notify(ctx, "Unable to create BTW side session.", "error");

package/extensions/tests/btw-history.mjs

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import { clampBtwScrollTop, getBtwPageScrollSize } from "../btw-scroll.ts";
+
+assert.equal(getBtwPageScrollSize(18), 18, "page scrolling uses the transcript viewport height");
+assert.equal(getBtwPageScrollSize(8.9), 8, "page scrolling uses a whole number of lines");
+assert.equal(getBtwPageScrollSize(0), 1, "page scrolling always moves at least one line");
+
+assert.equal(clampBtwScrollTop(-3, 20, 8), 0, "scroll top clamps at the start");
+assert.equal(clampBtwScrollTop(4, 20, 8), 4, "scroll top remains inside the range");
+assert.equal(clampBtwScrollTop(99, 20, 8), 12, "scroll top clamps at the end");
+assert.equal(clampBtwScrollTop(5, 4, 8), 0, "short content cannot scroll");
+assert.equal(clampBtwScrollTop(Number.NaN, 20, 8), 0, "invalid scroll input falls back to the start");
+
+console.log("BTW history scrolling tests passed");

package/global/AGENTS.md

@@ -100,11 +100,10 @@ After each significant step:
 2. Does the standard library cover it? Use it.
 3. Only then: write the minimum code that works.
 
----
+## 9. Use Available Editing Tools
 
+**Follow the current harness's tool surface; do not assume a shell patch helper exists.**
 
-## Output Format Preference
-
-For complex explanations, prefer a runnable HTML artifact over a long Markdown-only response when the content benefits from visual structure or interaction. This includes workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Keep ordinary prose, short answers, diffs, and focused code reviews in Markdown.
-
-When using HTML, create a self-contained, responsive artifact in the project's established output location, or `.cache/html/<descriptive-name>.html` when no convention exists. Use semantic HTML, accessible controls, escaped code blocks, and small useful interactions. Return a concise Markdown summary with a clickable local file path; if a preview/server tool is available, start it and return the preview URL only after verifying the page is not blank and its assets load.
+- Use the native file-editing tools exposed by the current environment. In pi, use `edit` for precise replacements and `write` for new files or complete rewrites.
+- Do not run `apply_patch` as a shell command unless `command -v apply_patch` confirms that executable is available.
+- If the harness exposes `apply_patch` as a dedicated tool rather than a command, invoke it only through that tool interface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
@@ -43,7 +43,7 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs",
+    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs",
     "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",