@pi-unipi/btw 3.0.0-alpha.4 → 3.0.0-alpha.41

package/README.md

@@ -1,23 +1,69 @@
-# @pi-unipi/btw
+# BTW
 
-`/unipi:btw [question]` opens an inline panel over the input area for a quick side question — the main agent keeps running and never sees any of it.
+Ask a side question while the main agent works, without adding it to the main conversation.
 
-Each question runs in a fresh read-only pi session seeded from the main session's current branch (including in-progress tool calls). There is **no memory between btw questions** — earlier Q&As are not fed back. Page history lives only for the pi session and is cleared on new/resume/tree navigation. Nothing is written to the main session.
+`@pi-unipi/btw` · part of [UniPi](../../README.md)
 
-## Panel
+## What it does
 
+- Opens a panel in place of the input box. The main agent continues to run.
+- Answers each question in a new, read-only session. This session starts with a copy of the main conversation, with tool calls that are in progress.
+- Gives the side session four tools only: `read`, `grep`, `find` and `ls`. It cannot run commands or change files.
+- Uses the model and the thinking level of the main session.
+- Writes nothing to the main session. The main agent never sees the question or the answer.
+- Keeps no memory between questions. Each question starts again from the main conversation.
+
+## Quick start
+
+UniPi installs this package:
+
+```bash
+pi install npm:@pi-unipi/unipi
 ```
-❭ <question>          your question
-… / ✓ tool lines      read-only tools only (read, grep, find, ls)
-Thinking..            while waiting
-answer                rendered as markdown
-❭ Ask a /btw…         input (locked while streaming)
+
+To install this package alone:
+
+```bash
+pi install npm:@pi-unipi/btw
 ```
 
-- `Enter` ask · `↑`/`↓` (empty input) page earlier Q&As · `PgUp`/`PgDn` scroll long answers · `Ctrl+C` cancel the answer · `Esc` back to the chat (a streaming answer keeps running into history; reopen with `/unipi:btw`).
+Then ask a question:
+
+```text
+/unipi:btw what does the retry loop in client.ts do?
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/unipi:btw [question]` | Opens the panel. If you give a question, the panel starts to answer it. |
+
+In print mode (no UI), `/unipi:btw <question>` shows the answer as a notification. A question is necessary in this mode.
+
+## Panel keys
+
+| Key | What it does |
+|---|---|
+| `Enter` | Asks the question in the input. It does nothing while an answer streams. |
+| `↑` / `↓` | Shows an earlier or later question and answer. Works when the input is empty. |
+| `PgUp` / `PgDn` | Scrolls a long answer. |
+| `Ctrl+C` | Stops the answer that streams. If no answer streams, it closes the panel. |
+| `Esc` | Closes the panel. An answer that streams continues and goes into the history. |
+
+Run `/unipi:btw` again to open the history. Only one answer can stream at a time.
+
+## How it works
+
+The panel shows each question, a line for each tool call, and the answer as markdown. The history stays in memory for the Pi session only. BTW clears it when a session starts or resumes, and when you move in the session tree.
+
+If you want a change to your files, ask in the main conversation.
+
+Older sessions can contain `btw-note` messages from an earlier BTW version. BTW still shows these messages and hides them from the model.
 
-Read-only: `read`, `grep`, `find`, `ls` only — no commands, no file changes. If you want something changed, ask in the main conversation.
+BTW comes from [pi-btw](https://github.com/Neuron-Mr-White/pi-btw) by Dan Bachelder.
 
-Without a UI (print mode), `/unipi:btw <question>` prints the answer via notify.
+## See also
 
-Based on [pi-btw](https://github.com/Neuron-Mr-White/pi-btw) by Dan Bachelder.
+- [Ask User](../ask-user/README.md)
+- [Commands reference](../../docs/reference/commands.md)

package/extensions/btw.ts

@@ -147,16 +147,64 @@ export function buildSeedEntries(ctx: {
 // ─── Page history (session-memory only, never persisted) ───────────────────
 
 export interface BtwPage {
+  /** Stable id (`btw-<pid>-<n>`), shared by the TUI panel and the app bridge
+   *  (the bridge's `btw_delta`/`btw_end` `id` and `btw_list` page ids). */
+  id: string;
   question: string;
   /** One line per tool call: "… Reading <p>" while running → "✓ <desc>" */
   toolLines: string[];
   answer: string;
+  /** Text streamed so far (the final `answer` lands at the end). */
+  partial: string;
+  /** Model reasoning streamed so far (kept for `btw_list` replays). */
+  thinking: string;
   error?: string;
   aborted?: boolean;
   done: boolean;
+  /** Token usage for the one assistant response (bridge forwards it in `btw_end`). */
+  usage?: { input: number; output: number; totalTokens: number };
 }
 
 const pages: BtwPage[] = [];
+let pageSeq = 0;
+
+/** A fresh page with a process-unique id. */
+export function newPage(question: string): BtwPage {
+  return { id: `btw-${process.pid}-${++pageSeq}`, question, toolLines: [], answer: "", partial: "", thinking: "", done: false };
+}
+
+/** One page as the app bridge's `btw_list` sends it. `question`/`answer`/
+ *  `error` keep their original meaning (older apps read only those); `id`,
+ *  `done`/`running` and `toolLines` let the app reconcile its own pages.
+ *  A running page's `answer` is the text streamed so far. */
+export interface BtwListPage {
+  id: string;
+  question: string;
+  answer: string;
+  error?: string;
+  done: boolean;
+  running: boolean;
+  toolLines?: string[];
+  /** Running pages only: the tail of the model's reasoning so far. */
+  thinking?: string;
+}
+
+/** Tail kept for a running page's `thinking` in `btw_list`. */
+const LIST_THINKING_TAIL = 2000;
+
+/** Read-only snapshot of recent pages for a `btw_list{}` reply — never mutate the result. */
+export function listPages(): BtwListPage[] {
+  return pages.map((p) => ({
+    id: p.id,
+    question: p.question,
+    answer: p.done ? p.answer : p.partial,
+    ...(p.error ? { error: p.error } : {}),
+    done: p.done,
+    running: !p.done,
+    ...(p.toolLines.length ? { toolLines: [...p.toolLines] } : {}),
+    ...(!p.done && p.thinking ? { thinking: p.thinking.slice(-LIST_THINKING_TAIL) } : {}),
+  }));
+}
 
 /** ↑/↓ paging reducer — clamp the target index into [0, count-1]. */
 export function pageIndexAfter(current: number, delta: number, count: number): number {
@@ -210,12 +258,20 @@ export function formatToolLine(
   return `${mark} ${label}${detail}`;
 }
 
+/** Delta kinds forwarded to `onDelta` (the bridge's UI-free API streams these
+ *  to the phone as `btw_delta`; the TUI panel ignores it — it re-renders
+ *  `page.answer`/`toolLines` from `onUpdate` instead). */
+export type BtwDeltaKind = "text" | "thinking" | "tool";
+
 function runQuestion(
   ctx: ExtensionCommandContext,
   question: string,
   page: BtwPage,
   thinkingLevel: AiThinkingLevel,
   onUpdate: () => void,
+  /** `index` (tool deltas only): the `page.toolLines` slot this line fills —
+   *  a tool's "done" line replaces its own "running" line. */
+  onDelta?: (kind: BtwDeltaKind, text: string, index?: number) => void,
 ): BtwRun {
   let session: AgentSession | null = null;
   let unsubscribe: (() => void) | null = null;
@@ -253,8 +309,10 @@ function runQuestion(
           const e = event as { toolCallId: string; toolName: string; args?: Record<string, unknown> };
           pendingStarts.set(e.toolCallId, { args: e.args });
           lineIndex.set(e.toolCallId, page.toolLines.length);
-          page.toolLines.push(formatToolLine(e.toolName, e.args, ctx.cwd, "running"));
+          const line = formatToolLine(e.toolName, e.args, ctx.cwd, "running");
+          page.toolLines.push(line);
           onUpdate();
+          onDelta?.("tool", line, page.toolLines.length - 1);
         } else if (event.type === "tool_execution_end") {
           const e = event as { toolCallId: string; toolName: string; isError: boolean };
           const start = pendingStarts.get(e.toolCallId);
@@ -264,6 +322,17 @@ function runQuestion(
           else page.toolLines.push(line);
           pendingStarts.delete(e.toolCallId);
           onUpdate();
+          onDelta?.("tool", line, idx ?? page.toolLines.length - 1);
+        } else if (event.type === "message_update") {
+          const e = event as { assistantMessageEvent?: { type?: string; delta?: string } };
+          if (e.assistantMessageEvent?.type === "text_delta" && e.assistantMessageEvent.delta) {
+            page.partial += e.assistantMessageEvent.delta;
+            onDelta?.("text", e.assistantMessageEvent.delta);
+          }
+          else if (e.assistantMessageEvent?.type === "thinking_delta" && e.assistantMessageEvent.delta) {
+            page.thinking += e.assistantMessageEvent.delta;
+            onDelta?.("thinking", e.assistantMessageEvent.delta);
+          }
         }
       });
 
@@ -279,6 +348,7 @@ function runQuestion(
         page.error = response.errorMessage || "request failed";
       } else {
         page.answer = extractText(response.content, "text") || "(no text)";
+        if (response.usage) page.usage = { input: response.usage.input, output: response.usage.output, totalTokens: response.usage.totalTokens };
       }
     } catch (err) {
       page.error = err instanceof Error ? err.message : String(err);
@@ -455,7 +525,65 @@ class BtwPanel implements Component {
   dispose(): void {}
 }
 
-// ─── Extension ──────────────────────────────────────────────────────────────
+// ─── UI-free API (the app bridge, no TUI needed) ───────────────────
+
+/** One streamed update from `BtwApi.ask` (mirrors the bridge's `btw_delta`/`btw_end`). */
+export type BtwEvent =
+  | { type: "delta"; kind: BtwDeltaKind; text: string; index?: number }
+  | { type: "end"; answer: string; error?: string; usage?: { input: number; output: number; totalTokens: number } };
+
+export interface BtwApi {
+  /** Starts a question, streaming `onEvent` until it ends (also resolved by `finished`).
+   *  Only one question runs at a time (shared with the TUI panel): a second call while
+   *  one is in flight ends immediately with an error. */
+  ask(cctx: ExtensionCommandContext, question: string, onEvent: (event: BtwEvent) => void): { id: string; finished: Promise<void> };
+  /** Recent pages for this pi session — shared with the TUI panel. */
+  list(): BtwListPage[];
+}
+
+const BTW_API_KEY = Symbol.for("unipi.btw.api");
+
+/** Publishes the UI-free API on globalThis so the app bridge (a sibling
+ *  extension, no shared module instance guaranteed) can ask a side question
+ *  without a TUI: `(globalThis as any)[Symbol.for("unipi.btw.api")]`. */
+function publishUiFreeApi(pi: ExtensionAPI, getActiveRun: () => BtwRun | null, setActiveRun: (run: BtwRun | null) => void): void {
+  let idSeq = 0;
+  const api: BtwApi = {
+    ask(cctx, question, onEvent) {
+      if (getActiveRun()) {
+        const id = `btw-${process.pid}-busy-${++idSeq}`;
+        const finished = Promise.resolve().then(() => onEvent({ type: "end", answer: "", error: "btw is already answering another question" }));
+        return { id, finished };
+      }
+      const page = newPage(question);
+      const id = page.id;
+      pages.push(page);
+      const run = runQuestion(
+        cctx,
+        question,
+        page,
+        pi.getThinkingLevel() as AiThinkingLevel,
+        () => {},
+        (kind, text, index) => onEvent(index === undefined ? { type: "delta", kind, text } : { type: "delta", kind, text, index }),
+      );
+      setActiveRun(run);
+      const finished = run.finished.then(() => {
+        setActiveRun(null);
+        onEvent({ type: "end", answer: page.answer, error: page.error, usage: page.usage });
+      });
+      return { id, finished };
+    },
+    list: () => listPages(),
+  };
+  (globalThis as unknown as Record<symbol, unknown>)[BTW_API_KEY] = api;
+}
+
+/** Reads the published API, or undefined when @pi-unipi/btw is not loaded. */
+export function getBtwApi(): BtwApi | undefined {
+  return (globalThis as unknown as Record<symbol, unknown>)[BTW_API_KEY] as BtwApi | undefined;
+}
+
+// ─── Extension ─────────────────────────────────────────────────────────────────────
 
 export default function btwExtension(pi: ExtensionAPI): void {
   let panelRef: BtwPanel | null = null;
@@ -466,7 +594,7 @@ export default function btwExtension(pi: ExtensionAPI): void {
 
   function startRun(ctx: ExtensionCommandContext, question: string): void {
     if (activeRun) return; // never two answers at once
-    const page: BtwPage = { question, toolLines: [], answer: "", done: false };
+    const page = newPage(question);
     const index = pages.length;
     pages.push(page);
     const run = runQuestion(ctx, question, page, pi.getThinkingLevel() as AiThinkingLevel, () => panelRef?.tick());
@@ -510,7 +638,7 @@ export default function btwExtension(pi: ExtensionAPI): void {
   }
 
   async function headlessAsk(ctx: ExtensionCommandContext, question: string): Promise<void> {
-    const page: BtwPage = { question, toolLines: [], answer: "", done: false };
+    const page = newPage(question);
     pages.push(page);
     notify(ctx, `btw: ${question}`, "info");
     const run = runQuestion(ctx, question, page, pi.getThinkingLevel() as AiThinkingLevel, () => {});
@@ -520,6 +648,8 @@ export default function btwExtension(pi: ExtensionAPI): void {
     notify(ctx, page.error ? `btw failed: ${page.error}` : `btw: ${page.answer}`, page.error ? "error" : "info");
   }
 
+  publishUiFreeApi(pi, () => activeRun, (run) => (activeRun = run));
+
   pi.on("session_start", () => {
     abortActiveRun();
     clearPages();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.41",
   "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.87.1"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.4"
+    "@pi-unipi/core": "3.0.0-alpha.41"
   },
   "pi": {
     "extensions": [