@narumitw/pi-btw 0.56.2 → 0.57.1

package/README.md

@@ -9,7 +9,7 @@ Only context you explicitly bring back is loaded into the main editor.
 
 - Starts a side thread immediately with `/btw <question>` or opens the manager with `/btw`.
 - Uses any persisted main-session branch as context without switching branches.
-- Supports scrollable answers, transcript search, follow-up questions, queued steering, and in-memory resume.
+- Supports scrollable answers, transcript search, a clickable jump-to-latest control, follow-up questions, queued steering, and in-memory resume.
 - Keeps side questions and answers out of the main conversation by default.
 - Brings back the latest answer, a question suffix, an exact range, or the complete thread only when requested.
 - Uses Pi's current model and thinking level or saved pi-btw choices.
@@ -43,114 +43,16 @@ The side thread stays separate until you explicitly bring context to the main ed
 
 ## 💬 Commands
 
-`/btw` is TUI-only.
-Open the manager or provide the first question immediately:
+| Command | Purpose |
+| --- | --- |
+| `/btw` | Choose context, start or resume a side thread, or change settings. |
+| `/btw <question>` | Start a new side thread immediately with the supplied question. |
 
-```text
-/btw
-/btw <your side question>
-```
-
-Examples:
-
-```text
-/btw
-/btw what does this TypeScript error mean?
-/btw summarize the current implementation before we continue
-/btw is this API name idiomatic?
-```
-
-### Choose context or resume a thread
-
-Running `/btw` opens a manager with **Start side thread** selected first.
-**Start from main thread tree…** opens Pi's session tree and uses the root-to-selected-entry path, including the selected entry, as context.
-This choice preserves the main editor draft and does not navigate, fork, append to, or switch the main conversation.
-The tree is a snapshot of persisted entries, and the side thread keeps immutable context even if the main conversation later changes.
-Escape returns to the manager, and Ctrl+C closes the flow.
-Native tree copying reports success or failure.
-An explicit `Shift+L` label edit is the only main-session mutation available from this selector and persists through Pi.
-
-When non-empty threads exist in memory, **Resume side thread** opens a bounded searchable list.
-Search matches the first question and question count while retaining each raw thread ID.
-Each row uses the first question as its fixed title and shows the question count.
-Rows are ordered by the newest recorded answer or visible error; opening and closing without a new result does not reorder them.
-**Settings** controls the starting thinking level, fixed-level shortcut memory, and automatic selection copying.
-`/btw <question>` bypasses the manager and always starts a new thread.
-
-### Use the side-thread workspace
-
-The side thread uses a dedicated full-screen terminal view with answers above the editor.
-The main agent can continue running, but main-screen rendering stays suspended until `/btw` closes so new output cannot move a mouse selection.
-Returning to Pi redraws everything produced while the main view was hidden.
-
-A fixed `btw · side thread` header identifies the workspace while scrolling.
-Messages use Pi's normal user and assistant presentation without turn numbers or role labels.
-Type a question and press Enter for each turn.
-Previous successful questions and answers remain visible and available to the side model.
-
-Drag the primary mouse button across transcript text to select it.
-Automatic selection copying is on by default and immediately requests a copy through Pi's host clipboard helper.
-When **Copy selection automatically** is off, the selection stays highlighted and Pi's effective `app.message.copy` binding copies it.
-Manual mode requires Pi's current fullscreen selection APIs.
-If those APIs are 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` when that binding is used without an active selection.
-It reports `Copied!` when Pi accepts a clipboard request and `Copy failed` when Pi rejects it.
-Actual clipboard access still depends on the operating system and terminal.
-Ctrl+C always cancels the side flow, even when `app.message.copy` is also mapped to Ctrl+C.
-
-Press `Ctrl+Shift+F` to search completed or in-progress transcript content.
-Press Enter or `Ctrl+G` for the next match, `Shift+Enter` or `Ctrl+Shift+G` for the previous match, and Escape to close search.
-Search uses Pi's active theme, excludes fixed header and footer text, and returns focus to the composer when closed.
-
-### Change thinking level or queue steering
-
-The header shows the side thread's current thinking level.
-In the composer, use Pi's configured `app.thinking.cycle` shortcut (`Shift+Tab` by default) to cycle levels supported by the side model.
-Later questions use the displayed level until it changes again.
-For a fixed starting level, shortcut changes are saved to `pi-btw.json` by default.
-Turn **Remember thinking level changes** off to keep them local to the thread.
-With **Same as main thread**, shortcut changes are always local.
-Neither setting changes the main session's thinking level.
-
-During a response, the transcript and composer remain visible above `Answering…`.
-Submit another question to queue it as `Steering`.
-Queued questions appear in submission order and run one at a time after the active response.
-Each queued question uses the side thread's thinking level when its turn starts.
-A failed response remains visible and does not discard later queued questions.
-Steering never appends to the main conversation or editor.
-
-Use the mouse wheel, trackpad, or `PgUp`/`PgDn` to scroll transcript history.
-The footer shows history keys only when scrolling is available.
-Ctrl+C cancels the active response and discards the current draft and steering queue.
-Completed questions, answers, and visible errors remain available through Resume until the extension instance ends.
-
-### Bring context to the main editor
-
-After a successful answer, press `Ctrl+R` to choose context for the main editor.
-The scope menu shows the size of the latest question and answer and the full thread.
-Choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
-Question-suffix, exact-range, and full-thread choices preview the editable context block before the side thread closes.
-Escape returns, while Ctrl+C closes without bringing context back.
-
-The exact-range selector supports whole-line and editor-style character selection.
-It reports selected line, message, and approximate token counts.
-Press Space to select the current raw source line, use Up or Down to extend by lines, and press Space again to clear.
-Alternatively, move with arrow keys and extend a character selection with Shift plus an arrow key.
-Starting a Shift selection replaces an active line selection.
-Selected lines show a `●` marker as well as highlighting.
-Pi's configured keys control vertical navigation, bringing, and going back, with Up, Down, Enter, and Escape as defaults.
-Selection follows raw source text rather than terminal-wrapped rows.
-
-Bringing context closes the side thread and loads a deterministic, editable block into Pi's main editor without sending it.
-If a draft already exists, append is the recommended default.
-Replace is marked destructive and requires a second confirmation.
-Cancel returns to the side thread without changing either draft, and concurrent editor updates are preserved.
-A success message reports whether context was loaded, appended, or replaced and gives its approximate size.
-
-Without an explicit bring action, closing `/btw` never changes the main conversation.
-Non-empty threads remain in memory only for Resume during the current extension instance.
-`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard retained threads.
-Unsent drafts, steering queues, interrupted answers, and model credentials are not retained.
+Both routes require TUI mode and a model with usable credentials; see [Settings](#-settings).
+Side questions and selected conversation context are sent to that model's provider.
+Bringing context back fills the main editor without submitting; replacing an existing draft requires confirmation.
+Ctrl+C cancels the response and discards the current draft and queued questions, but completed exchanges remain resumable in memory.
+Read the [workflow guide](./docs/workflows.md) for context selection, copying, search, steering, and draft recovery; `/new`, `/resume`, `/reload`, and restart discard retained threads.
 
 ## ⚙️ Settings
 
@@ -216,43 +118,22 @@ The file is read for every `/btw` invocation, so edits apply without `/reload`.
 - Resume state is memory-only and lasts only for the current extension instance.
 - A side thread retains the latest 40,000 characters of main-conversation context and adds a truncation notice when earlier content is omitted.
 - Clipboard access depends on Pi's host helper, the operating system, and the terminal.
+- Pi versions before 0.85 omit the clickable jump-to-latest control.
 
 ## 🗂️ Package layout
 
-```txt
+```text
 packages/pi-btw/
-├── dist/                  # Generated TypeScript runtime loaded by Jiti
-├── scripts/
-│   └── build-runtime.mjs  # Deterministic runtime builder and boundary validator
-├── src/
-│   ├── index.ts
-│   ├── btw.ts
-│   ├── bring-to-main.ts
-│   ├── fullscreen-ui.ts
-│   ├── main-tree-picker.ts
-│   ├── menu.ts
-│   ├── settings.ts
-│   ├── side-thread.ts
-│   ├── text.ts
-│   └── transcript-pager.ts
-├── test/
-├── README.md
-├── LICENSE
-├── tsconfig.json
-└── package.json
-```
-
-The package exposes its Pi extension through `package.json`:
-
-```json
-{
-  "pi": {
-    "extensions": ["./dist/index.ts"]
-  }
-}
+├── src/                               # Authoritative implementation and helpers
+│   ├── index.ts                       # Thin Pi entrypoint
+│   └── btw.ts                         # Side-thread lifecycle and command
+├── dist/                              # Generated Jiti runtime
+├── docs/                              # Side-thread workflows and controls
+├── scripts/build-runtime.mjs          # Runtime builder
+└── test/                              # Behavior and lifecycle coverage
 ```
 
-The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
+The generated runtime is built from `src/index.ts` and does not import back into `src`.
 
 ## 🔎 Keywords
 

package/dist/index.ts

@@ -482,8 +482,10 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
   isKeyRelease,
+  isKittyProtocolActive,
   Key as Key2,
   matchesKey as matchesKey2,
+  parseKey,
   TuiAltScreen,
   truncateToWidth as truncateToWidth2
 } from "@earendil-works/pi-tui";
@@ -495,6 +497,18 @@ function sanitizeSingleLine(text) {
     return code > 31 && (code < 127 || code > 159);
   }).join("").replace(/ +/gu, " ").trim();
 }
+function formatKeyLabel2(key) {
+  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("+");
+}
 
 // src/fullscreen-ui.ts
 var FullscreenUiDisposedError = class extends Error {
@@ -607,6 +621,88 @@ var BtwTuiAltScreen = class extends TuiAltScreen {
 };
 var BRACKETED_PASTE_START = "\x1B[200~";
 var BRACKETED_PASTE_END = "\x1B[201~";
+var 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"
+];
+var KEY_MODIFIER_ORDER = ["shift", "ctrl", "alt", "super"];
+var MATCHABLE_SPECIAL_KEYS = /* @__PURE__ */ new Set([
+  "space",
+  "tab",
+  "enter",
+  "backspace",
+  "delete",
+  "insert",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right"
+]);
+var MATCHABLE_SYMBOL_KEYS = new Set("`-=[]\\;',./!@#$%^&*()_+|~{}:<>?");
+function normalizedKeyId(key) {
+  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) {
+  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 formatKeyLabel2(parts.join("+"));
+}
+function canMatchKeyInput(key) {
+  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) {
+  if (base.length !== 1) return void 0;
+  const rawBase = base === "-" ? "_" : base;
+  if (!"abcdefghijklmnopqrstuvwxyz[\\]_".includes(rawBase)) return void 0;
+  return String.fromCharCode(rawBase.charCodeAt(0) & 31);
+}
+function legacyRawInput(key) {
+  const parts = key.split("+");
+  const base = parts.at(-1) ?? "";
+  if (parts.length === 2 && parts[0] === "ctrl") return rawCtrlInput(base);
+  if (isKittyProtocolActive()) return void 0;
+  if (parts.length === 2 && parts[0] === "alt" && base.length === 1) return `\x1B${base}`;
+  if (parts.length === 3 && parts[0] === "ctrl" && parts[1] === "alt") {
+    const input = rawCtrlInput(base);
+    return input ? `\x1B${input}` : void 0;
+  }
+  return void 0;
+}
+function keyInputIdentity(key) {
+  const identity = normalizedKeyId(key);
+  const input = legacyRawInput(identity);
+  return input ? normalizedKeyId(parseKey(input) ?? identity) : identity;
+}
 function hasManualSelectionCopyApi() {
   return typeof TuiAltScreen.prototype.hasActiveSelection === "function" && typeof TuiAltScreen.prototype.copyActiveSelectionToClipboard === "function";
 }
@@ -625,6 +721,25 @@ function createBtwFullscreenTui(parent, theme, keybindings, copyOnSelect, manual
       mouse: true,
       copyOnSelect,
       searchMatchStyle: (text) => theme.underline(styleSearchMatch(text)),
+      scrollToEndIndicator: () => {
+        const unavailableKeyIdentities = /* @__PURE__ */ new Set([keyInputIdentity(Key2.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", " \u2193 Jump to latest message");
+        const shortcut = key ? theme.fg("muted", ` \xB7 ${formatEffectiveKeyLabel(key)}`) : "";
+        return theme.bg("selectedBg", `${label}${shortcut} `);
+      },
       searchCurrentMatchStyle: (text) => theme.bold(theme.inverse(styleSearchMatch(text))),
       openUrl,
       copySelection: async (text) => {
@@ -1010,14 +1125,15 @@ async function completeSideThreadTurn({
   thinkingLevel,
   auth,
   signal,
-  completeSimple
+  completeSimple,
+  sessionId
 }) {
   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)) {
@@ -1076,10 +1192,31 @@ function createUserMessage(text) {
     timestamp: Date.now()
   };
 }
-function buildStreamOptions(auth, thinkingLevel, signal) {
+var OPENCODE_HOST = "opencode.ai";
+function matchesOpencodeHost(baseUrl) {
+  if (!baseUrl) return false;
+  try {
+    return new URL(baseUrl).hostname === OPENCODE_HOST;
+  } catch {
+    return false;
+  }
+}
+function getOpencodeSessionHeaders(model, sessionId) {
+  if (!sessionId) return void 0;
+  if (model.provider !== "opencode" && model.provider !== "opencode-go" && !matchesOpencodeHost(model.baseUrl)) {
+    return void 0;
+  }
+  return { "x-opencode-session": sessionId, "x-opencode-client": "pi" };
+}
+function mergeSessionHeaders(authHeaders, sessionHeaders) {
+  if (!sessionHeaders && !authHeaders) return void 0;
+  return { ...sessionHeaders, ...authHeaders };
+}
+function buildStreamOptions(auth, { thinkingLevel, signal, model, sessionId }) {
+  const sessionHeaders = model ? getOpencodeSessionHeaders(model, sessionId) : void 0;
   const options = {
     apiKey: auth.apiKey,
-    headers: auth.headers,
+    headers: mergeSessionHeaders(auth.headers, sessionHeaders),
     env: auth.env,
     signal
   };
@@ -2376,14 +2513,7 @@ function renderSideThreadHeader(width, theme, thinkingLevel) {
   return theme.fg("muted", `${title}${"\u2500".repeat(ruleWidth)}`);
 }
 function thinkingKeyLabel(keybindings) {
-  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 formatKeyLabel2(String(keybindings.getKeys("app.thinking.cycle")[0] ?? "shift+tab")) || "Shift+Tab";
 }
 function fitComposerLayout(header, contentLines, footer, editorLines, availableRows, statusLines = []) {
   const lines = [header, ...contentLines, ...statusLines, footer, ...editorLines];
@@ -2507,6 +2637,12 @@ function providerHeadersHaveValue(headers) {
 function formatError5(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function readBtwSessionId(ctx) {
+  const getSessionId = ctx.sessionManager.getSessionId;
+  if (typeof getSessionId !== "function") return void 0;
+  const sessionId = getSessionId.call(ctx.sessionManager);
+  return sessionId.length > 0 ? sessionId : void 0;
+}
 function notifySafely3(ctx, message, level) {
   try {
     ctx.ui.notify(sanitizeSingleLine(message), level);
@@ -3041,7 +3177,8 @@ async function askThreadQuestion(thread, question, selected, thinkingLevel, ctx,
         thinkingLevel,
         auth: selected.auth,
         signal: view.signal,
-        completeSimple: createModelRegistryCompleteSimple(ctx.modelRegistry)
+        completeSimple: createModelRegistryCompleteSimple(ctx.modelRegistry),
+        sessionId: readBtwSessionId(ctx)
       }).then((result) => {
         if (settled) return;
         settled = true;