@narumitw/pi-btw 0.56.2 → 0.57.1

package/docs/workflows.md

@@ -0,0 +1,73 @@
+# 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 Pi's `app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle supported levels for later questions.
+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.
+
+Ctrl+C 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.
+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.56.2",
+	"version": "0.57.1",
 	"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"
 	],
@@ -32,9 +33,9 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.11",
-		"@earendil-works/pi-ai": "0.84.4",
-		"@earendil-works/pi-coding-agent": "0.84.4",
-		"@earendil-works/pi-tui": "0.84.4",
+		"@earendil-works/pi-ai": "0.85.0",
+		"@earendil-works/pi-coding-agent": "0.85.0",
+		"@earendil-works/pi-tui": "0.85.0",
 		"esbuild": "0.28.2",
 		"typescript": "7.0.2"
 	},

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,
@@ -895,6 +902,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

@@ -8,16 +8,18 @@ import {
 import {
 	type Component,
 	isKeyRelease,
+	isKittyProtocolActive,
 	Key,
 	matchesKey,
 	type OverlayHandle,
+	parseKey,
 	type TUI,
 	TuiAltScreen,
 	type TuiInputListener,
 	type TuiInputListenerResult,
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
-import { sanitizeSingleLine } from "./text.js";
+import { formatKeyLabel, sanitizeSingleLine } from "./text.js";
 
 type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
 type BtwCustomFactory<T> = (
@@ -205,6 +207,103 @@ class BtwTuiAltScreen extends TuiAltScreen {
 const BRACKETED_PASTE_START = "\u001b[200~";
 const BRACKETED_PASTE_END = "\u001b[201~";
 
+// TuiAltScreen evaluates these actions before bottom, so shared keys cannot jump to latest.
+const ALT_SCREEN_ACTIONS_BEFORE_BOTTOM = [
+	"tui.altScreen.search",
+	"tui.altScreen.searchNext",
+	"tui.altScreen.searchPrevious",
+	"tui.altScreen.searchClose",
+	"tui.altScreen.pageUp",
+	"tui.altScreen.pageDown",
+	"tui.altScreen.halfPageUp",
+	"tui.altScreen.halfPageDown",
+	"tui.altScreen.lineUp",
+	"tui.altScreen.lineDown",
+	"tui.altScreen.previousPrompt",
+	"tui.altScreen.nextPrompt",
+	"tui.altScreen.top",
+] as const;
+const KEY_MODIFIER_ORDER = ["shift", "ctrl", "alt", "super"] as const;
+const MATCHABLE_SPECIAL_KEYS = new Set([
+	"space",
+	"tab",
+	"enter",
+	"backspace",
+	"delete",
+	"insert",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+]);
+const MATCHABLE_SYMBOL_KEYS = new Set("`-=[]\\;',./!@#$%^&*()_+|~{}:<>?");
+
+function normalizedKeyId(key: string): string {
+	const parts = key.toLowerCase().split("+");
+	const base = parts.at(-1);
+	if (!base) return "";
+	const normalizedBase = base === "esc" ? "escape" : base === "return" ? "enter" : base;
+	const modifiers = KEY_MODIFIER_ORDER.filter((modifier) => parts.includes(modifier));
+	return [...modifiers, normalizedBase].join("+");
+}
+
+function formatEffectiveKeyLabel(key: string): string {
+	const parts = key.split("+");
+	const base = parts.at(-1);
+	if (base === "pageup") parts[parts.length - 1] = "pageUp";
+	if (base === "pagedown") parts[parts.length - 1] = "pageDown";
+	return formatKeyLabel(parts.join("+"));
+}
+
+function canMatchKeyInput(key: string): boolean {
+	const parts = key.split("+");
+	const base = parts.at(-1) ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (base === "escape") return modifiers.length === 0;
+	if (base === "clear") {
+		return (
+			modifiers.length === 0 ||
+			(modifiers.length === 1 && (modifiers[0] === "shift" || modifiers[0] === "ctrl"))
+		);
+	}
+	if (/^f(?:[1-9]|1[0-2])$/u.test(base)) return modifiers.length === 0;
+	return (
+		MATCHABLE_SPECIAL_KEYS.has(base) ||
+		(base.length === 1 && (/^[a-z0-9]$/u.test(base) || MATCHABLE_SYMBOL_KEYS.has(base)))
+	);
+}
+
+function rawCtrlInput(base: string): string | undefined {
+	if (base.length !== 1) return undefined;
+	const rawBase = base === "-" ? "_" : base;
+	if (!"abcdefghijklmnopqrstuvwxyz[\\]_".includes(rawBase)) return undefined;
+	return String.fromCharCode(rawBase.charCodeAt(0) & 0x1f);
+}
+
+function legacyRawInput(key: string): string | undefined {
+	const parts = key.split("+");
+	const base = parts.at(-1) ?? "";
+	if (parts.length === 2 && parts[0] === "ctrl") return rawCtrlInput(base);
+	if (isKittyProtocolActive()) return undefined;
+	if (parts.length === 2 && parts[0] === "alt" && base.length === 1) return `\u001b${base}`;
+	if (parts.length === 3 && parts[0] === "ctrl" && parts[1] === "alt") {
+		const input = rawCtrlInput(base);
+		return input ? `\u001b${input}` : undefined;
+	}
+	return undefined;
+}
+
+// Mirror matchesKey(), using parseKey() to canonicalize IDs that share legacy raw input.
+function keyInputIdentity(key: string): string {
+	const identity = normalizedKeyId(key);
+	const input = legacyRawInput(identity);
+	return input ? normalizedKeyId(parseKey(input) ?? identity) : identity;
+}
+
 function hasManualSelectionCopyApi(): boolean {
 	return (
 		typeof TuiAltScreen.prototype.hasActiveSelection === "function" &&
@@ -236,6 +335,32 @@ function createBtwFullscreenTui(
 			mouse: true,
 			copyOnSelect,
 			searchMatchStyle: (text) => theme.underline(styleSearchMatch(text)),
+			scrollToEndIndicator: () => {
+				const unavailableKeyIdentities = new Set<string>([keyInputIdentity(Key.ctrl("c"))]);
+				for (const action of ALT_SCREEN_ACTIONS_BEFORE_BOTTOM) {
+					for (const actionKey of keybindings.getKeys(action)) {
+						unavailableKeyIdentities.add(keyInputIdentity(String(actionKey)));
+					}
+				}
+				if (!copyOnSelect) {
+					for (const copyKey of keybindings.getKeys("app.message.copy")) {
+						unavailableKeyIdentities.add(keyInputIdentity(String(copyKey)));
+					}
+				}
+				const key = keybindings
+					.getKeys("tui.altScreen.bottom")
+					.map((candidate) => keyInputIdentity(String(candidate)))
+					.find(
+						(identity) =>
+							identity &&
+							canMatchKeyInput(identity) &&
+							!unavailableKeyIdentities.has(identity) &&
+							formatEffectiveKeyLabel(identity),
+					);
+				const label = theme.fg("text", " ↓ Jump to latest message");
+				const shortcut = key ? theme.fg("muted", ` · ${formatEffectiveKeyLabel(key)}`) : "";
+				return theme.bg("selectedBg", `${label}${shortcut} `);
+			},
 			searchCurrentMatchStyle: (text) => theme.bold(theme.inverse(styleSearchMatch(text))),
 			openUrl,
 			copySelection: async (text) => {

package/src/side-thread.ts

@@ -86,6 +86,7 @@ export interface CompleteSideThreadTurnOptions {
 	auth: SideQuestionAuth;
 	signal?: AbortSignal;
 	completeSimple: CompleteSimpleFunction;
+	sessionId?: string;
 }
 
 export type CompleteSideThreadTurnResult =
@@ -101,13 +102,14 @@ export async function completeSideThreadTurn({
 	auth,
 	signal,
 	completeSimple,
+	sessionId,
 }: CompleteSideThreadTurnOptions): Promise<CompleteSideThreadTurnResult> {
 	if (signal?.aborted) return { kind: "aborted" };
 	try {
 		const response = await completeSimple(
 			model,
 			{ systemPrompt: SYSTEM_PROMPT, messages: buildSideThreadMessages(thread, question) },
-			buildStreamOptions(auth, thinkingLevel, signal),
+			buildStreamOptions(auth, { thinkingLevel, signal, model, sessionId }),
 		);
 		if (signal?.aborted || response?.stopReason === "aborted") return { kind: "aborted" };
 		if (!isAssistantMessage(response)) {
@@ -137,6 +139,7 @@ export interface CompleteSideQuestionOptions {
 	auth: SideQuestionAuth;
 	signal?: AbortSignal;
 	completeSimple: CompleteSimpleFunction;
+	sessionId?: string;
 }
 
 export async function completeSideQuestion({
@@ -147,6 +150,7 @@ export async function completeSideQuestion({
 	auth,
 	signal,
 	completeSimple,
+	sessionId,
 }: CompleteSideQuestionOptions): Promise<AssistantMessage> {
 	return completeSimple(
 		model,
@@ -154,7 +158,7 @@ export async function completeSideQuestion({
 			systemPrompt: SYSTEM_PROMPT,
 			messages: [createUserMessage(buildUserPrompt(question, conversationContext))],
 		},
-		buildStreamOptions(auth, thinkingLevel, signal),
+		buildStreamOptions(auth, { thinkingLevel, signal, model, sessionId }),
 	);
 }
 
@@ -214,14 +218,62 @@ function createUserMessage(text: string): UserMessage {
 	};
 }
 
+// Minimal session-headers fork of Pi core provider-attribution
+// (pinned to @earendil-works/pi-coding-agent@0.85.0 src/core/provider-attribution.ts:getSessionHeaders).
+// Core does not export this helper and extensions have no SettingsManager, so only session
+// headers are mirrored here. Default attribution headers are intentionally out of scope.
+// Keep semantics bug-compatible with core: case-sensitive Object.assign, explicit auth
+// headers win on exact-case match.
+const OPENCODE_HOST = "opencode.ai";
+
+function matchesOpencodeHost(baseUrl: string | undefined): boolean {
+	if (!baseUrl) return false;
+	try {
+		return new URL(baseUrl).hostname === OPENCODE_HOST;
+	} catch {
+		return false;
+	}
+}
+
+function getOpencodeSessionHeaders(
+	model: Pick<Model<Api>, "provider" | "baseUrl">,
+	sessionId?: string,
+): ProviderHeaders | undefined {
+	if (!sessionId) return undefined;
+	if (
+		model.provider !== "opencode" &&
+		model.provider !== "opencode-go" &&
+		!matchesOpencodeHost(model.baseUrl)
+	) {
+		return undefined;
+	}
+	return { "x-opencode-session": sessionId, "x-opencode-client": "pi" };
+}
+
+function mergeSessionHeaders(
+	authHeaders: ProviderHeaders | undefined,
+	sessionHeaders: ProviderHeaders | undefined,
+): ProviderHeaders | undefined {
+	if (!sessionHeaders && !authHeaders) return undefined;
+	// Bug-compatible with core mergeProviderAttributionHeaders: case-sensitive assign.
+	return { ...sessionHeaders, ...authHeaders };
+}
+
+interface BuildSideThreadStreamOptions {
+	thinkingLevel: BtwThinkingLevel;
+	signal?: AbortSignal;
+	model?: Pick<Model<Api>, "provider" | "baseUrl">;
+	sessionId?: string;
+}
+
 function buildStreamOptions(
 	auth: SideQuestionAuth,
-	thinkingLevel: BtwThinkingLevel,
-	signal?: AbortSignal,
+	{ thinkingLevel, signal, model, sessionId }: BuildSideThreadStreamOptions,
 ): SimpleStreamOptions {
+	const sessionHeaders = model ? getOpencodeSessionHeaders(model, sessionId) : undefined;
 	const options: SimpleStreamOptions = {
 		apiKey: auth.apiKey,
-		headers: auth.headers,
+		headers: mergeSessionHeaders(auth.headers, sessionHeaders),
 		env: auth.env,
 		signal,
 	};

package/src/text.ts

@@ -8,3 +8,21 @@ export function sanitizeSingleLine(text: string): string {
 		.replace(/ +/gu, " ")
 		.trim();
 }
+
+export function formatKeyLabel(key: string): string {
+	const sanitized = sanitizeSingleLine(key);
+	if (!sanitized) return "";
+	return sanitized
+		.split("+")
+		.map((part) => {
+			const lower = part.toLowerCase();
+			if (lower === "shift") return "Shift";
+			if (lower === "ctrl") return "Ctrl";
+			if (lower === "alt") return "Alt";
+			if (lower === "super") return "Super";
+			return part.length === 1
+				? part.toUpperCase()
+				: `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`;
+		})
+		.join("+");
+}

package/src/transcript-pager.ts

@@ -24,7 +24,7 @@ import {
 } from "@earendil-works/pi-tui";
 import type { BtwFullscreenLayoutComponent } from "./fullscreen-ui.js";
 import type { BtwThinkingLevel, SideThreadTurn } from "./side-thread.js";
-import { sanitizeSingleLine } from "./text.js";
+import { formatKeyLabel, sanitizeSingleLine } from "./text.js";
 
 const TRANSCRIPT_CHROME_LINES = 2;
 const MAX_STEERING_DISPLAY_LINES = 3;
@@ -613,21 +613,10 @@ function renderSideThreadHeader(
 }
 
 function thinkingKeyLabel(keybindings: KeybindingsManager): string {
-	const key =
-		sanitizeSingleLine(String(keybindings.getKeys("app.thinking.cycle")[0] ?? "shift+tab")) ||
-		"Shift+Tab";
-	return key
-		.split("+")
-		.map((part) => {
-			const lower = part.toLowerCase();
-			if (lower === "shift") return "Shift";
-			if (lower === "ctrl") return "Ctrl";
-			if (lower === "alt") return "Alt";
-			return part.length === 1
-				? part.toUpperCase()
-				: `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`;
-		})
-		.join("+");
+	return (
+		formatKeyLabel(String(keybindings.getKeys("app.thinking.cycle")[0] ?? "shift+tab")) ||
+		"Shift+Tab"
+	);
 }
 
 function fitComposerLayout(