@narumitw/pi-btw 0.57.1 → 0.58.1

package/docs/workflows.md

@@ -39,7 +39,8 @@ Click it or use Pi's effective `tui.altScreen.bottom` binding (`End` by default)
 ## Thinking and queued questions
 
 The header shows the current side-thread thinking level.
-Use Pi's `app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle supported levels for later questions.
+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`.
@@ -47,12 +48,12 @@ Queued questions run in order after the current response, using the thinking lev
 A failed response remains visible without discarding later queued questions.
 Steering does not append to the main conversation or editor.
 
-Ctrl+C cancels the active response and discards the current draft and steering queue.
+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, press `Ctrl+R` to choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-btw",
-	"version": "0.57.1",
+	"version": "0.58.1",
 	"description": "Pi extension that adds a /btw side-question command.",
 	"type": "module",
 	"license": "MIT",

package/src/btw.ts

@@ -146,7 +146,12 @@ export async function resolveBtwModel({
 				: `falling back to ${fallback}`;
 			try {
 				const auth = await modelRegistry.getApiKeyAndHeaders(configuredModel);
-				if (auth.ok && hasRequestAuth(auth)) return { model: configuredModel, auth };
+				if (auth.ok && hasRequestAuth(auth)) {
+					return {
+						model: auth.baseUrl ? { ...configuredModel, baseUrl: auth.baseUrl } : configuredModel,
+						auth,
+					};
+				}
 				const reason = auth.ok ? "has no request credentials" : auth.error;
 				reportWarning(
 					`pi-btw model ${settings.model} is unavailable (${reason}); ${fallbackAction}.`,
@@ -163,7 +168,13 @@ export async function resolveBtwModel({
 	if (!currentModel) return undefined;
 	try {
 		const auth = await modelRegistry.getApiKeyAndHeaders(currentModel);
-		if (auth.ok && hasRequestAuth(auth)) return { model: currentModel, auth };
+		if (auth.ok && hasRequestAuth(auth)) {
+			// Direct provider streams bypass Pi's request preparation, including OAuth routing.
+			return {
+				model: auth.baseUrl ? { ...currentModel, baseUrl: auth.baseUrl } : currentModel,
+				auth,
+			};
+		}
 	} catch {
 		// The caller reports the final lack of an available model.
 	}
@@ -223,6 +234,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,
@@ -349,7 +363,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) {

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;
+	}
+}