@narumitw/pi-btw 0.57.0 → 0.58.0

package/docs/workflows.md

@@ -0,0 +1,74 @@
+# Side-thread workflows
+
+[Back to README](../README.md#-commands)
+
+## Choose context and resume threads
+
+`/btw` lets you start from the current conversation or choose **Start from main thread tree…** to use the root-to-selected-entry path, including the selected entry.
+The tree snapshots persisted entries and preserves the main editor draft without navigating, forking, appending to, or switching the main conversation.
+Side-thread context stays immutable if the main conversation later changes.
+An explicit `Shift+L` label edit is the selector's only main-session mutation and persists through Pi.
+Native tree copying reports success or failure; Escape returns to the manager and Ctrl+C closes the flow.
+
+**Resume side thread** searches non-empty in-memory threads by their first question and question count.
+The first question remains the title; threads are ordered by their newest answer or visible error.
+Opening and closing without a new result does not reorder them.
+`/btw <question>` bypasses selection and always starts a new thread.
+
+## Read, select, and search
+
+The fullscreen workspace keeps answers above the editor and identifies itself with a fixed `btw · side thread` header.
+The main agent may keep running, but its rendering is suspended so new output cannot move a mouse selection; returning to Pi redraws that output.
+Submit each question with Enter; successful prior questions and answers remain available to the side model.
+
+Drag the primary mouse button across the transcript to select text.
+Automatic selection copying requests Pi's host clipboard helper immediately and is enabled by default.
+With **Copy selection automatically** off, the selection stays highlighted and Pi's effective `app.message.copy` binding copies it.
+Manual copying requires Pi's fullscreen selection APIs; if unavailable, pi-btw restores the main TUI and asks you to update Pi or re-enable automatic copying.
+The view reports `No selection to copy`, `Copied!`, or `Copy failed` for the request; actual clipboard access still depends on the operating system and terminal.
+Ctrl+C always cancels the side flow, even if `app.message.copy` is also mapped to Ctrl+C.
+
+Press `Ctrl+Shift+F` to search completed or in-progress transcript text, excluding the fixed header and footer.
+Enter or `Ctrl+G` finds the next match; `Shift+Enter` or `Ctrl+Shift+G` finds the previous match.
+Escape closes search and returns focus to the composer.
+
+Scroll with the mouse wheel, trackpad, or `PgUp`/`PgDn`.
+On Pi 0.85 or newer, scrolling away from the latest content reveals **Jump to latest message**.
+Click it or use Pi's effective `tui.altScreen.bottom` binding (`End` by default) to resume following new output.
+
+## Thinking and queued questions
+
+The header shows the current side-thread thinking level.
+Use the thinking-cycle shortcut shown in the composer to cycle supported levels for later questions.
+It inherits Pi's `app.thinking.cycle` (`Shift+Tab` by default) unless overridden in [Keybindings](../README.md#keybindings).
+Whether that change is remembered depends on [Settings](../README.md#-settings); it never changes the main session's thinking level.
+
+During a response, submit another question to queue it as `Steering`.
+Queued questions run in order after the current response, using the thinking level effective when each turn starts.
+A failed response remains visible without discarding later queued questions.
+Steering does not append to the main conversation or editor.
+
+The configured exit shortcut, or the permanent Ctrl+C hard-cancel key, cancels the active response and discards the current draft and steering queue.
+Completed questions, answers, and visible errors remain resumable until the extension instance ends.
+
+## Bring context to the main editor
+
+After a successful answer, use the bring-to-main shortcut (`Ctrl+R` by default) to choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
+The scope chooser reports the latest exchange and full-thread sizes.
+Question-suffix, exact-range, and full-thread choices preview an editable context block before closing the side thread.
+Escape returns; Ctrl+C closes without bringing context back.
+
+The exact-range selector works on raw source text, not terminal-wrapped rows, and reports line, message, and approximate token counts.
+Press Space to select the current raw line, extend with Up or Down, and press Space again to clear.
+Alternatively, move with arrow keys and extend character selection with Shift plus an arrow key; starting a Shift selection replaces an active line selection.
+Selected lines have a `●` marker and highlighting.
+Pi's effective navigation, submission, and back bindings apply, with Up, Down, Enter, and Escape as defaults.
+
+Bringing context closes the side thread and loads a deterministic, editable block into the main editor **without sending it**.
+For an existing draft, append is recommended; replace is destructive and requires a second confirmation.
+Cancel returns to the side thread without changing either draft, and concurrent editor updates are preserved.
+The success message reports whether context was loaded, appended, or replaced and its approximate size.
+
+Without an explicit bring action, closing `/btw` never changes the main conversation.
+Resume state is memory-only: `/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard it.
+Unsent drafts, steering queues, interrupted answers, and model credentials are not retained.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-btw",
-	"version": "0.57.0",
+	"version": "0.58.0",
 	"description": "Pi extension that adds a /btw side-question command.",
 	"type": "module",
 	"license": "MIT",
@@ -15,6 +15,7 @@
 	"files": [
 		"src",
 		"dist",
+		"docs",
 		"README.md",
 		"LICENSE"
 	],

package/src/btw.ts

@@ -204,6 +204,13 @@ function formatError(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function readBtwSessionId(ctx: ExtensionCommandContext): string | undefined {
+	const getSessionId = ctx.sessionManager.getSessionId;
+	if (typeof getSessionId !== "function") return undefined;
+	const sessionId = getSessionId.call(ctx.sessionManager);
+	return sessionId.length > 0 ? sessionId : undefined;
+}
+
 function notifySafely(
 	ctx: ExtensionCommandContext,
 	message: string,
@@ -216,6 +223,9 @@ function notifySafely(
 	}
 }
 
+// Keep this slightly-over-1,000-line command coordinator intact: its injectable menu,
+// request, resume, and delivery flows share the same thread-state and test seams;
+// settings, keybinding policy, terminal ownership, and rendering live in separate modules.
 export interface BtwExtensionDependencies {
 	showCommandMenu?: (
 		pi: ExtensionAPI,
@@ -342,7 +352,10 @@ export default function btw(pi: ExtensionAPI, dependencies: BtwExtensionDependen
 							ctx: fullscreenCtx,
 						});
 					},
-					{ copyOnSelect: effectiveFullscreenCopyOnSelect(settings) },
+					{
+						copyOnSelect: effectiveFullscreenCopyOnSelect(settings),
+						...(settings.keybindings ? { keybindings: settings.keybindings } : {}),
+					},
 				);
 			} finally {
 				if (state?.title && state.thread.turns.length > 0) {
@@ -895,6 +908,7 @@ async function askThreadQuestion(
 				auth: selected.auth,
 				signal: view.signal,
 				completeSimple: createModelRegistryCompleteSimple(ctx.modelRegistry),
+				sessionId: readBtwSessionId(ctx),
 			}).then((result) => {
 				if (settled) return;
 				settled = true;

package/src/fullscreen-ui.ts

@@ -10,7 +10,6 @@ import {
 	isKeyRelease,
 	isKittyProtocolActive,
 	Key,
-	matchesKey,
 	type OverlayHandle,
 	parseKey,
 	type TUI,
@@ -19,6 +18,12 @@ import {
 	type TuiInputListenerResult,
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
+import {
+	type BtwKeybindingOverrides,
+	BtwPasteGuard,
+	resolveBtwShortcuts,
+	setBtwShortcuts,
+} from "./keybindings.js";
 import { formatKeyLabel, sanitizeSingleLine } from "./text.js";
 
 type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
@@ -41,6 +46,7 @@ export interface BtwFullscreenLayoutComponent extends Component {
 }
 
 export interface BtwFullscreenOptions {
+	keybindings?: BtwKeybindingOverrides;
 	copyOnSelect?: boolean;
 }
 
@@ -473,13 +479,37 @@ class BtwFullscreenHost<T> implements Component {
 			this.fullscreen = this.createTui(this.parent, this.theme, this.keybindings, this.options);
 			this.fullscreenCreated = true;
 			this.fullscreen.start();
+			const shortcuts = resolveBtwShortcuts(
+				this.options.keybindings,
+				this.keybindings,
+				this.options.copyOnSelect ?? true,
+			);
+			setBtwShortcuts(this.fullscreen, shortcuts);
+			// Negotiate before warning when possible: the first dispatched user input uses
+			// the current mode. Recheck each input, including later mode transitions.
+			let previousWarnings: readonly string[] = [];
+			const reportWarnings = () => {
+				const warnings = shortcuts.warnings;
+				for (const warning of warnings) {
+					if (previousWarnings.includes(warning)) continue;
+					try {
+						this.ctx.ui.notify(`Pi BTW: ${warning}`, "warning");
+					} catch {
+						/* A replaced context must not prevent terminal cleanup. */
+					}
+				}
+				previousWarnings = warnings;
+			};
+			const pasteGuard = new BtwPasteGuard();
 			// Waiting for the custom promise would leave follow-up keys bound to the side TUI.
 			const addHardCancelListener =
 				this.fullscreen.addInputListenerBeforeAll?.bind(this.fullscreen) ??
 				this.fullscreen.addInputListenerBeforeViewport?.bind(this.fullscreen) ??
 				this.fullscreen.addInputListener.bind(this.fullscreen);
 			this.removeHardCancelListener = addHardCancelListener((data) => {
-				if (isKeyRelease(data) || !matchesKey(data, Key.ctrl("c"))) return undefined;
+				reportWarnings();
+				if (pasteGuard.consume(data) || !shortcuts.matches(data, "exit")) return undefined;
+				this.disposed = true;
 				try {
 					this.hardCancelActiveCustom?.();
 				} finally {

package/src/keybindings.ts

@@ -0,0 +1,330 @@
+import {
+	isKeyRelease,
+	isKittyProtocolActive,
+	KeybindingsManager,
+	type KeyId,
+	matchesKey,
+	type TUI,
+	TUI_KEYBINDINGS,
+} from "@earendil-works/pi-tui";
+import { formatKeyLabel } from "./text.js";
+
+export const BTW_SHORTCUT_ACTIONS = ["exit", "cycleThinkingLevel", "bringToMain"] as const;
+export type BtwShortcutAction = (typeof BTW_SHORTCUT_ACTIONS)[number];
+export type BtwKeybindingOverrides = Partial<Record<BtwShortcutAction, string>>;
+
+const MODIFIERS = ["shift", "alt", "ctrl", "super"] as const;
+const SYMBOLS = "`-=[]\\;',./!@#$%^&*()_|~{}:<>?";
+const SPECIAL: Record<string, number> = {
+	escape: 27,
+	tab: 9,
+	enter: 13,
+	space: 32,
+	backspace: 127,
+	insert: 57425,
+	delete: 57426,
+	home: 57423,
+	end: 57424,
+	pageup: 57421,
+	pagedown: 57422,
+	left: 57417,
+	right: 57418,
+	up: 57419,
+	down: 57420,
+};
+const FUNCTION_INPUTS = [
+	"OP",
+	"OQ",
+	"OR",
+	"OS",
+	"[15~",
+	"[17~",
+	"[18~",
+	"[19~",
+	"[20~",
+	"[21~",
+	"[23~",
+	"[24~",
+];
+// All cross-identity legacy collisions in Pi's matchesKey(): raw Ctrl bytes,
+// ESC-prefixed bytes (including Alt+arrows), BS/DEL, Enter and Shift+Tab.
+// CSI-u, keypad, lock bits, shifted letters and modifyOtherKeys normalize to
+// the same key+modifiers; probe that identity instead of duplicating the parser.
+const LEGACY_INPUTS = [
+	...Array.from({ length: 128 }, (_, code) => String.fromCharCode(code)),
+	...Array.from({ length: 128 }, (_, code) => `\u001b${String.fromCharCode(code)}`),
+	"\u001b[Z",
+	"\u001bOM",
+	"\u001b[E",
+	"\u001b[e",
+	"\u001bOe",
+	...FUNCTION_INPUTS.map((suffix) => `\u001b${suffix}`),
+];
+
+/** Strict settings syntax; Pi itself ignores unknown/duplicate modifier tokens. */
+export function normalizeBtwKey(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.length > 80 || /[\s\p{Cc}]/u.test(value)) return undefined;
+	const parts = value.toLowerCase().split("+");
+	let base = parts.pop();
+	if (!base) return undefined;
+	if (base === "esc") base = "escape";
+	if (base === "return") base = "enter";
+	if (
+		new Set(parts).size !== parts.length ||
+		parts.some((part) => !MODIFIERS.includes(part as never))
+	)
+		return undefined;
+	if (
+		!Object.hasOwn(SPECIAL, base) &&
+		base !== "clear" &&
+		!/^f(?:[1-9]|1[0-2])$/u.test(base) &&
+		!(base.length === 1 && (/^[a-z0-9]$/u.test(base) || SYMBOLS.includes(base)))
+	)
+		return undefined;
+	if ((base === "escape" || (base.startsWith("f") && base.length > 1)) && parts.length)
+		return undefined;
+	if (
+		base === "clear" &&
+		(parts.length > 1 || (parts.length === 1 && !["ctrl", "shift"].includes(parts[0] ?? "")))
+	)
+		return undefined;
+	return [...MODIFIERS.filter((part) => parts.includes(part)), base].join("+");
+}
+
+/** Representative inputs are checked by Pi, including its live terminal-mode branches. */
+function inputsFor(key: string): string[] {
+	const parts = key.split("+");
+	const base = parts.pop() ?? "";
+	const modifier = MODIFIERS.reduce(
+		(mask, part, bit) => mask | (parts.includes(part) ? 1 << bit : 0),
+		0,
+	);
+	const code = SPECIAL[base] ?? (base.length === 1 ? base.charCodeAt(0) : undefined);
+	const inputs =
+		code === undefined ? LEGACY_INPUTS : [...LEGACY_INPUTS, `\u001b[${code};${modifier + 1}u`];
+	return inputs.filter((input) => matchesKey(input, key as KeyId));
+}
+
+export function btwKeysOverlap(first: string, second: string): boolean {
+	const normalized = normalizeBtwKey(first);
+	return (
+		normalized !== undefined &&
+		inputsFor(normalized).some((input) => matchesKey(input, second as KeyId))
+	);
+}
+
+export interface BtwShortcuts {
+	keys: Record<BtwShortcutAction, readonly string[]>;
+	warnings: readonly string[];
+	matches(data: string, action: BtwShortcutAction): boolean;
+	label(action: BtwShortcutAction): string;
+}
+
+function reservedKeys(keybindings: KeybindingsManager, copyOnSelect: boolean): string[] {
+	// Editor has no autocomplete provider here. Select bindings are still reserved
+	// because exit also applies to BTW-owned nested review/menu components.
+	return [
+		"ctrl+c",
+		"shift+backspace",
+		"shift+delete",
+		"shift+space",
+		// Exact-range review uses these fixed selection actions even if Editor is remapped.
+		"shift+left",
+		"shift+right",
+		"shift+up",
+		"shift+down",
+		"left",
+		"right",
+		"enter",
+		"alt+enter",
+		"ctrl+j",
+		"pageUp",
+		"pageDown",
+		...Object.keys(TUI_KEYBINDINGS).flatMap((id) =>
+			keybindings.getKeys(id as keyof typeof TUI_KEYBINDINGS),
+		),
+		...(!copyOnSelect ? keybindings.getKeys("app.message.copy") : []),
+	];
+}
+
+function isTextKey(key: string): boolean {
+	const parts = key.split("+");
+	const base = parts.at(-1) ?? "";
+	return (
+		(base.length === 1 || base === "space") &&
+		!parts.some((part) => ["ctrl", "alt", "super"].includes(part))
+	);
+}
+
+export function resolveBtwShortcuts(
+	overrides: BtwKeybindingOverrides = {},
+	keybindings: KeybindingsManager,
+	copyOnSelect = true,
+): BtwShortcuts {
+	let mode = isKittyProtocolActive();
+	let snapshot = resolveShortcutSnapshot(overrides, keybindings, copyOnSelect);
+	const current = () => {
+		if (mode !== isKittyProtocolActive()) {
+			mode = isKittyProtocolActive();
+			snapshot = resolveShortcutSnapshot(overrides, keybindings, copyOnSelect);
+		}
+		return snapshot;
+	};
+	// ProcessTerminal negotiates Kitty asynchronously after the dedicated TUI starts.
+	// Hints and matching must use the same policy after that mode transition.
+	return {
+		get keys() {
+			return current().keys;
+		},
+		get warnings() {
+			return current().warnings;
+		},
+		matches: (data, action) => current().matches(data, action),
+		label: (action) => current().label(action),
+	};
+}
+
+function resolveShortcutSnapshot(
+	overrides: BtwKeybindingOverrides = {},
+	keybindings: KeybindingsManager,
+	copyOnSelect = true,
+): BtwShortcuts {
+	const reserved = reservedKeys(keybindings, copyOnSelect);
+	const keys: BtwShortcuts["keys"] = { exit: ["ctrl+c"], cycleThinkingLevel: [], bringToMain: [] };
+	const warnings: string[] = [];
+	const defaults: Record<BtwShortcutAction, readonly string[]> = {
+		exit: ["ctrl+c"],
+		cycleThinkingLevel: keybindings.getKeys("app.thinking.cycle"),
+		bringToMain: ["ctrl+r"],
+	};
+	const usable = (
+		action: BtwShortcutAction,
+		candidate: string,
+		inherited = false,
+	): string | undefined => {
+		const key = normalizeBtwKey(candidate);
+		if (!key || (!inherited && isTextKey(key))) return undefined;
+		const inputs = inputsFor(key);
+		if (!inputs.length) return undefined;
+		if (action === "exit" && key === "ctrl+c") return key;
+		if (
+			reserved.some(
+				(other) =>
+					typeof other === "string" && inputs.some((input) => matchesKey(input, other as KeyId)),
+			)
+		)
+			return undefined;
+		return key;
+	};
+	const candidates: BtwKeybindingOverrides = {};
+	const availableDefaults = { ...defaults };
+	for (const action of BTW_SHORTCUT_ACTIONS) {
+		availableDefaults[action] = defaults[action]
+			.map((key) => usable(action, key, action === "cycleThinkingLevel"))
+			.filter((key): key is string => key !== undefined);
+		const override = overrides[action];
+		if (override !== undefined) candidates[action] = usable(action, override);
+	}
+	// Compare the complete proposal, not only actions visited earlier. Reject conflicts
+	// together, then repeat because a rejected override restores its default bindings.
+	for (;;) {
+		const rejected = BTW_SHORTCUT_ACTIONS.filter((action) => {
+			const candidate = candidates[action];
+			return (
+				candidate !== undefined &&
+				BTW_SHORTCUT_ACTIONS.some(
+					(other) =>
+						other !== action &&
+						(candidates[other] ? [candidates[other]] : availableDefaults[other]).some((key) =>
+							btwKeysOverlap(candidate, key),
+						),
+				)
+			);
+		});
+		if (!rejected.length) break;
+		for (const action of rejected) delete candidates[action];
+	}
+	for (const action of BTW_SHORTCUT_ACTIONS) {
+		const override = overrides[action];
+		const selected = candidates[action];
+		if (override !== undefined && !selected)
+			warnings.push(
+				`${action}: configured shortcut is invalid or conflicts with a reserved action; using an available default.`,
+			);
+		const effective = selected
+			? [selected]
+			: availableDefaults[action].filter(
+					(key) =>
+						!BTW_SHORTCUT_ACTIONS.some(
+							(other) => other !== action && keys[other].some((used) => btwKeysOverlap(key, used)),
+						),
+				);
+		keys[action] = action === "exit" ? [...new Set([...effective, "ctrl+c"])] : effective;
+		if (!keys[action].length && (override !== undefined || defaults[action].length > 0))
+			warnings.push(`${action}: no usable shortcut; change Pi BTW Settings or Pi keybindings.`);
+	}
+	return {
+		keys,
+		warnings,
+		matches: (data, action) =>
+			!isKeyRelease(data) && keys[action].some((key) => matchesKey(data, key as KeyId)),
+		label: (action) =>
+			keys[action].length ? formatKeyLabel(keys[action][0] ?? "") : "Unavailable",
+	};
+}
+
+export function validateBtwShortcutEdit(
+	action: BtwShortcutAction,
+	value: string | undefined,
+	overrides: BtwKeybindingOverrides,
+	keybindings: KeybindingsManager,
+	copyOnSelect: boolean,
+): string | undefined {
+	// Reset must remain available even when several existing overrides conflict.
+	if (value === undefined) return undefined;
+	if (!normalizeBtwKey(value))
+		return "Invalid key combination. Use a Pi key name such as ctrl+q or f6.";
+	const next = { ...overrides, [action]: value };
+	const resolved = resolveBtwShortcuts(next, keybindings, copyOnSelect);
+	const previous = resolveBtwShortcuts(overrides, keybindings, copyOnSelect);
+	// Reject edits that disable another binding as well as the edited binding.
+	for (const item of BTW_SHORTCUT_ACTIONS) {
+		if (
+			(item === action && !resolved.keys[item].includes(normalizeBtwKey(value) ?? "")) ||
+			(item !== action && previous.keys[item].some((key) => !resolved.keys[item].includes(key)))
+		) {
+			return `${item} conflicts with another BTW shortcut, editing, selection, search, scrolling, or copying. Choose a different key.`;
+		}
+	}
+	return undefined;
+}
+
+const bindingsByTui = new WeakMap<TUI, BtwShortcuts>();
+export function setBtwShortcuts(tui: TUI, shortcuts: BtwShortcuts): void {
+	bindingsByTui.set(tui, shortcuts);
+}
+export function getBtwShortcuts(tui: TUI, keybindings?: KeybindingsManager): BtwShortcuts {
+	return (
+		bindingsByTui.get(tui) ??
+		resolveBtwShortcuts(
+			{},
+			keybindings ??
+				new KeybindingsManager({
+					...TUI_KEYBINDINGS,
+					"app.thinking.cycle": { defaultKeys: "shift+tab" },
+				}),
+		)
+	);
+}
+
+/** Keep split bracketed-paste payloads away from screen-level shortcuts. */
+export class BtwPasteGuard {
+	private active = false;
+	consume(data: string): boolean {
+		const wasActive = this.active;
+		const starts = data.includes("\u001b[200~");
+		if (starts) this.active = true;
+		if (this.active && data.includes("\u001b[201~")) this.active = false;
+		return wasActive || starts;
+	}
+}