@howaboua/pi-smart-btw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Warzocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# pi-smart-btw
+
+`@howaboua/pi-smart-btw` adds `/btw <question>` to Pi: an async, ephemeral side session for questions you do not want to derail the main conversation. It starts a fresh no-session Pi RPC subprocess, renders side answers in the transcript, lets you ask follow-ups with more `/btw ...`, and injects the side-session result only when you choose.
+
+- Fresh context: child starts with `pi --mode rpc --no-session`.
+- Full tools/extensions/skills: no `--no-skills`; installed extensions load normally except this extension disables itself in the child to avoid nesting UI.
+- Async main session: the command starts work in the background and returns immediately.
+- Compose: press `alt+z` to prefill `/btw ` in the prompt editor.
+- Injection: press `alt+c` from the UI while the btw block is visible.
+- Dismiss: press `alt+x` from the UI while the btw block is visible.
+- Only one slash command is registered: `/btw`.
+- Side answers are rendered as display-only custom transcript messages and filtered from the LLM context with Pi's `context` hook. They are only sent to the main agent when you explicitly inject them. The widget shows status/actions only.
+
+## Install
+
+```bash
+pi install npm:@howaboua/pi-smart-btw
+```
+
+Or try it for one session without adding it permanently:
+
+```bash
+pi -e npm:@howaboua/pi-smart-btw
+```
+
+## Usage
+
+```text
+/btw explain this error without interrupting the current task
+```
+
+While the side session is open:
+
+- run another `/btw ...` to ask a follow-up in the same child session
+- press `alt+c` to inject all completed side-session turns into the main chat
+- press `alt+x` to dismiss and stop the child session
+- press `alt+z` to prefill `/btw ` in the editor
+
+Injection format for one turn:
+
+```text
+The user asked the following question in a separate session:
+[Q]
+The answer was:
+[A]
+Take it into account while executing the current task.
+```
+
+For multiple completed turns, injection includes every question/answer pair in order.
+
+## Configuration
+
+Config is created at `~/.pi/agent/pi-smart-btw.json`:
+
+```json
+{
+  "model": "openai-codex/gpt-5.4-mini",
+  "provider": "",
+  "thinking": "low",
+  "command": "pi",
+  "injectShortcut": "alt+c",
+  "dismissShortcut": "alt+x",
+  "composeShortcut": "alt+z"
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run pack:dry-run
+```
+

package/index.ts

@@ -0,0 +1,180 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { ensureConfig, readConfig } from "./src/config.js";
+import { BtwChild } from "./src/rpc-child.js";
+import type { BtwTurn } from "./src/types.js";
+
+const WIDGET_ID = "smart-btw";
+const MESSAGE_TYPE = "smart-btw-result";
+const FALLBACK_COMPOSE_SHORTCUT = "alt+z";
+const FALLBACK_INJECT_SHORTCUT = "alt+c";
+const FALLBACK_DISMISS_SHORTCUT = "alt+x";
+
+type State = {
+  child?: BtwChild;
+  turns: BtwTurn[];
+  running: boolean;
+  queue: Promise<void>;
+  ctx?: ExtensionCommandContext;
+};
+
+function doneTurns(turns: BtwTurn[]) {
+  return turns.filter((turn) => turn.answer || turn.error);
+}
+
+function injectionText(turns: BtwTurn[]) {
+  const completed = doneTurns(turns);
+  if (completed.length === 1) {
+    const turn = completed[0]!;
+    return [
+      "The user asked the following question in a separate session:",
+      turn.question,
+      "The answer was:",
+      turn.answer || turn.error || "(no answer)",
+      "Take it into account while executing the current task.",
+    ].join("\n");
+  }
+
+  return [
+    "The user asked the following questions in a separate session:",
+    ...completed.flatMap((turn, index) => [
+      "",
+      `Question ${index + 1}:`,
+      turn.question,
+      "Answer:",
+      turn.answer || turn.error || "(no answer)",
+    ]),
+    "",
+    "Take them into account while executing the current task.",
+  ].join("\n");
+}
+
+function render(ctx: ExtensionCommandContext, state: State) {
+  const t = ctx.ui.theme;
+  if (!state.child && state.turns.length === 0) {
+    ctx.ui.setWidget(WIDGET_ID, undefined);
+    return;
+  }
+  const cfg = readConfig();
+  const lines: string[] = [];
+  const status = state.running ? t.fg("warning", "running") : t.fg("success", "ready");
+  lines.push(`${t.fg("accent", "╭─ btw")} ${status} ${t.fg("dim", `${cfg.model}:${cfg.thinking}`)}`);
+  for (const turn of state.turns.slice(-3)) {
+    const q = turn.question.length > 120 ? `${turn.question.slice(0, 117)}...` : turn.question;
+    lines.push(`${t.fg("muted", "│ Q")} ${q}`);
+    if (turn.error) lines.push(`${t.fg("error", "│ ✗ failed — see btw result in transcript")}`);
+    else if (turn.answer) lines.push(`${t.fg("success", "│ ✓ answered — see btw result in transcript")}`);
+    else lines.push(`${t.fg("warning", "│ … thinking")}`);
+  }
+  lines.push(`${t.fg("muted", "╰─")} ${FALLBACK_COMPOSE_SHORTCUT} compose · ${FALLBACK_INJECT_SHORTCUT} inject · ${FALLBACK_DISMISS_SHORTCUT} dismiss`);
+  ctx.ui.setWidget(WIDGET_ID, lines, { placement: "aboveEditor" });
+}
+
+function sendResultMessage(pi: ExtensionAPI, turn: BtwTurn) {
+  pi.sendMessage({
+    customType: MESSAGE_TYPE,
+    content: turn.answer || turn.error || "(no answer)",
+    display: true,
+    details: {
+      question: turn.question,
+      answer: turn.answer,
+      error: turn.error,
+      startedAt: turn.startedAt,
+      finishedAt: turn.finishedAt,
+    },
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  if (process.env.PI_SMART_BTW_CHILD === "1") return;
+  ensureConfig();
+  pi.registerMessageRenderer(MESSAGE_TYPE, (message, _options, theme) => {
+    const details = message.details as { question?: string; answer?: string; error?: string } | undefined;
+    const box = new Box(1, 1, (value) => theme.bg("customMessageBg", value));
+    const status = details?.error ? theme.fg("error", "btw failed") : theme.fg("accent", "btw");
+    const question = details?.question ?? "";
+    const body = details?.answer ?? details?.error ?? String(message.content ?? "");
+    box.addChild(new Text(`${status} ${theme.fg("muted", "Q")} ${question}\n\n${body}`, 0, 0));
+    return box;
+  });
+
+  pi.on("context", async (event) => ({
+    messages: event.messages.filter((message) => {
+      const candidate = message as { role?: string; customType?: string };
+      return !(candidate.role === "custom" && candidate.customType === MESSAGE_TYPE);
+    }),
+  }));
+  const state: State = { turns: [], running: false, queue: Promise.resolve() };
+
+  const dismiss = async () => {
+    await state.child?.stop();
+    state.child = undefined;
+    state.turns = [];
+    state.running = false;
+    state.ctx?.ui.setWidget(WIDGET_ID, undefined);
+  };
+
+  const inject = () => {
+    const turns = doneTurns(state.turns);
+    if (turns.length === 0) {
+      state.ctx?.ui.notify("No /btw answer to inject yet.", "warning");
+      return;
+    }
+    pi.sendUserMessage(injectionText(turns), state.ctx?.isIdle() ? undefined : { deliverAs: "followUp" });
+  };
+
+  const cfg = readConfig();
+  for (const key of [cfg.composeShortcut, FALLBACK_COMPOSE_SHORTCUT].filter((key, index, keys) => keys.indexOf(key) === index)) {
+    pi.registerShortcut(key as any, {
+      description: "Prefill /btw in the prompt editor",
+      handler: async (ctx) => {
+        const current = ctx.ui.getEditorText();
+        const prefix = current.trim() ? `${current.trimEnd()} /btw ` : "/btw ";
+        ctx.ui.setEditorText(prefix);
+      },
+    });
+  }
+  for (const key of [cfg.injectShortcut, FALLBACK_INJECT_SHORTCUT].filter((key, index, keys) => keys.indexOf(key) === index)) {
+    pi.registerShortcut(key as any, { description: "Inject latest /btw answer into the main session", handler: async () => inject() });
+  }
+  for (const key of [cfg.dismissShortcut, FALLBACK_DISMISS_SHORTCUT].filter((key, index, keys) => keys.indexOf(key) === index)) {
+    pi.registerShortcut(key as any, { description: "Dismiss active /btw block", handler: async () => { await dismiss(); } });
+  }
+
+  pi.registerCommand("btw", {
+    description: "Ask a fresh async side-session question. Re-run while open to ask a follow-up. UI: inject/dismiss shortcuts shown in the btw block.",
+    handler: async (args, ctx) => {
+      const question = args.trim();
+      state.ctx = ctx;
+      if (!question) {
+        ctx.ui.notify("Usage: /btw <question>", "warning");
+        return;
+      }
+      const turn: BtwTurn = { question, startedAt: Date.now() };
+      state.turns.push(turn);
+      render(ctx, state);
+
+      state.queue = state.queue.then(async () => {
+        state.running = true;
+        render(ctx, state);
+        try {
+          if (!state.child) {
+            state.child = new BtwChild(ctx.cwd, () => render(ctx, state));
+            await state.child.ready();
+          }
+          turn.answer = await state.child.ask(question) || "(no answer)";
+        } catch (error) {
+          turn.error = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`/btw failed: ${turn.error}`, "error");
+        } finally {
+          turn.finishedAt = Date.now();
+          state.running = false;
+          render(ctx, state);
+          if (turn.answer || turn.error) sendResultMessage(pi, turn);
+        }
+      });
+    },
+  });
+
+  pi.on("session_shutdown", async () => { await state.child?.stop(); });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@howaboua/pi-smart-btw",
+  "version": "0.1.0",
+  "description": "Async side-session questions for Pi with explicit injection into the main chat.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.1",
+    "@earendil-works/pi-coding-agent": "^0.74.1",
+    "@earendil-works/pi-tui": "^0.74.1",
+    "@types/node": "^24.10.0",
+    "typescript": "^5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "side-session",
+    "btw",
+    "subagent",
+    "async"
+  ],
+  "author": "Igor Warzocha",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorWarzocha/pi-smart-btw.git"
+  },
+  "homepage": "https://github.com/IgorWarzocha/pi-smart-btw#readme",
+  "bugs": {
+    "url": "https://github.com/IgorWarzocha/pi-smart-btw/issues"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { BtwConfig, ThinkingLevel } from "./types.js";
+
+const ALLOWED = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh"]);
+const DEFAULT_CONFIG: Required<BtwConfig> = {
+  model: "openai-codex/gpt-5.4-mini",
+  provider: "",
+  thinking: "low",
+  command: "pi",
+  injectShortcut: "alt+c",
+  dismissShortcut: "alt+x",
+  composeShortcut: "alt+z",
+};
+
+function agentDir() {
+  return process.env.PI_CODING_AGENT_DIR?.trim() || path.join(os.homedir(), ".pi", "agent");
+}
+
+export function configPath() { return path.join(agentDir(), "pi-smart-btw.json"); }
+
+export function ensureConfig() {
+  fs.mkdirSync(agentDir(), { recursive: true });
+  if (!fs.existsSync(configPath())) fs.writeFileSync(configPath(), JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+}
+
+export function readConfig(): Required<BtwConfig> {
+  ensureConfig();
+  let parsed: Partial<BtwConfig> = {};
+  try { parsed = JSON.parse(fs.readFileSync(configPath(), "utf8")); } catch {}
+  const model = typeof parsed.model === "string" && parsed.model.trim() ? parsed.model.trim() : DEFAULT_CONFIG.model;
+  const thinking = parsed.thinking && ALLOWED.has(parsed.thinking) ? parsed.thinking : DEFAULT_CONFIG.thinking;
+  return {
+    model,
+    provider: typeof parsed.provider === "string" ? parsed.provider : DEFAULT_CONFIG.provider,
+    thinking,
+    command: typeof parsed.command === "string" && parsed.command.trim() ? parsed.command.trim() : DEFAULT_CONFIG.command,
+    injectShortcut: typeof parsed.injectShortcut === "string" && parsed.injectShortcut.trim() ? parsed.injectShortcut.trim() : DEFAULT_CONFIG.injectShortcut,
+    dismissShortcut: typeof parsed.dismissShortcut === "string" && parsed.dismissShortcut.trim() ? parsed.dismissShortcut.trim() : DEFAULT_CONFIG.dismissShortcut,
+    composeShortcut: typeof parsed.composeShortcut === "string" && parsed.composeShortcut.trim() ? parsed.composeShortcut.trim() : DEFAULT_CONFIG.composeShortcut,
+  };
+}

package/src/rpc-child.ts

@@ -0,0 +1,140 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildDetails } from "./types.js";
+import { readConfig } from "./config.js";
+
+const READY_TIMEOUT = 10_000;
+const RESPONSE_TIMEOUT = 30_000;
+const QUIET_MS = 500;
+const POLL_MS = 150;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function getFinalOutput(messages: any[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "assistant") continue;
+    for (const part of message.content ?? []) if (part.type === "text") return part.text;
+  }
+  return "";
+}
+
+export class BtwChild {
+  readonly details: ChildDetails;
+  private proc: ChildProcessWithoutNullStreams;
+  private requestId = 0;
+  private stdoutBuffer = "";
+  private pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timeout: ReturnType<typeof setTimeout> }>();
+  private lastEventAt = Date.now();
+  private agentEndCount = 0;
+  private closed = false;
+  private exitCode: number | undefined;
+
+  constructor(private cwd: string, private onUpdate?: () => void) {
+    const cfg = readConfig();
+    const args = ["--mode", "rpc", "--no-session", "--model", cfg.model, "--thinking", cfg.thinking];
+    this.details = {
+      cwd,
+      model: cfg.model,
+      thinking: cfg.thinking,
+      messages: [],
+      stderr: "",
+      usage: { turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0 },
+    };
+    this.proc = spawn(cfg.command, args, { cwd, shell: false, stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, PI_SMART_BTW_CHILD: "1" } });
+    this.proc.stdout.on("data", (chunk) => this.onStdout(chunk.toString()));
+    this.proc.stderr.on("data", (chunk) => { this.details.stderr += chunk.toString(); this.onUpdate?.(); });
+    this.proc.on("close", (code) => { this.closed = true; this.exitCode = code ?? 0; this.rejectAll(new Error(`btw child exited with code ${this.exitCode}`)); });
+    this.proc.on("error", (error) => this.rejectAll(error instanceof Error ? error : new Error(String(error))));
+  }
+
+  async ready() {
+    await this.send({ type: "get_state" }, READY_TIMEOUT);
+    await this.send({ type: "set_auto_compaction", enabled: true });
+    await this.send({ type: "set_auto_retry", enabled: true });
+  }
+
+  async ask(question: string) {
+    this.agentEndCount = 0;
+    const before = this.details.messages.length;
+    const prompt = [
+      "Answer the user's question directly.",
+      "Use available tools only if they are needed to answer accurately.",
+      "Be concise unless the question requires detail.",
+      `Question: ${question}`,
+    ].join("\n\n");
+    await this.send({ type: "prompt", message: prompt, streamingBehavior: "followUp" });
+    await this.waitForAnswer(before);
+    return getFinalOutput(this.details.messages).trim();
+  }
+
+  async stop() {
+    if (this.closed) return;
+    this.proc.kill("SIGTERM");
+    await Promise.race([new Promise<void>((resolve) => this.proc.once("close", () => resolve())), sleep(1000).then(() => { if (!this.closed) this.proc.kill("SIGKILL"); })]);
+  }
+
+  private async waitForAnswer(beforeCount: number) {
+    while (!this.closed) {
+      await sleep(POLL_MS);
+      const state = await this.send<{ isStreaming: boolean; isCompacting: boolean; pendingMessageCount: number }>({ type: "get_state" });
+      const idle = !state.isStreaming && !state.isCompacting && state.pendingMessageCount === 0;
+      const quiet = Date.now() - this.lastEventAt >= QUIET_MS;
+      if (this.agentEndCount > 0 && idle && quiet && this.details.messages.length > beforeCount) return;
+    }
+    throw new Error(`btw child closed.${this.details.stderr ? ` Stderr: ${this.details.stderr.trim()}` : ""}`);
+  }
+
+  private send<T = unknown>(command: Record<string, unknown>, timeoutMs = RESPONSE_TIMEOUT): Promise<T> {
+    if (this.closed || !this.proc.stdin.writable) throw new Error("btw child RPC is not available");
+    const id = `req_${++this.requestId}`;
+    return new Promise<T>((resolve, reject) => {
+      const timeout = setTimeout(() => { this.pending.delete(id); reject(new Error(`Timed out waiting for ${String(command.type)}`)); }, timeoutMs);
+      this.pending.set(id, { resolve: (v) => resolve(v as T), reject, timeout });
+      this.proc.stdin.write(JSON.stringify({ ...command, id }) + "\n", (err) => {
+        if (!err) return;
+        clearTimeout(timeout); this.pending.delete(id); reject(err instanceof Error ? err : new Error(String(err)));
+      });
+    });
+  }
+
+  private onStdout(chunk: string) {
+    this.stdoutBuffer += chunk;
+    const lines = this.stdoutBuffer.split("\n");
+    this.stdoutBuffer = lines.pop() ?? "";
+    for (const line of lines) this.handleLine(line);
+  }
+
+  private handleLine(line: string) {
+    if (!line.trim()) return;
+    let data: any;
+    try { data = JSON.parse(line); } catch { return; }
+    if (data.type === "response" && typeof data.id === "string" && this.pending.has(data.id)) {
+      const pending = this.pending.get(data.id)!;
+      clearTimeout(pending.timeout); this.pending.delete(data.id);
+      data.success === false ? pending.reject(new Error(String(data.error ?? `RPC ${data.command} failed`))) : pending.resolve(data.data);
+      return;
+    }
+    this.lastEventAt = Date.now();
+    if (data.type === "agent_end") this.agentEndCount++;
+    if (data.type === "message_end" && data.message) {
+      this.details.messages.push(data.message);
+      if (data.message.role === "assistant") {
+        this.details.usage.turns++;
+        const u = data.message.usage;
+        if (u) {
+          this.details.usage.input += u.input || 0; this.details.usage.output += u.output || 0;
+          this.details.usage.cacheRead += u.cacheRead || 0; this.details.usage.cacheWrite += u.cacheWrite || 0;
+          this.details.usage.cost += u.cost?.total || 0; this.details.usage.contextTokens = u.totalTokens || 0;
+        }
+        if (data.message.stopReason) this.details.stopReason = data.message.stopReason;
+        if (data.message.errorMessage) this.details.errorMessage = data.message.errorMessage;
+      }
+      this.onUpdate?.();
+    }
+  }
+
+  private rejectAll(error: Error) {
+    for (const p of this.pending.values()) { clearTimeout(p.timeout); p.reject(error); }
+    this.pending.clear();
+  }
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+import type { Message } from "@earendil-works/pi-ai";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export interface BtwConfig {
+  model: string;
+  thinking?: ThinkingLevel;
+  provider?: string;
+  command?: string;
+  injectShortcut?: string;
+  dismissShortcut?: string;
+  composeShortcut?: string;
+}
+
+export interface BtwTurn {
+  question: string;
+  answer?: string;
+  error?: string;
+  startedAt: number;
+  finishedAt?: number;
+}
+
+export interface ChildDetails {
+  cwd: string;
+  model: string;
+  thinking?: ThinkingLevel;
+  messages: Message[];
+  stderr: string;
+  usage: { turns: number; input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; contextTokens: number };
+  stopReason?: string;
+  errorMessage?: string;
+}