pi-btw 0.1.1 → 0.2.1

package/extensions/btw.ts

@@ -1,21 +1,41 @@
 import {
   buildSessionContext,
+  createAgentSession,
+  createExtensionRuntime,
+  codingTools,
+  SessionManager,
+  type AgentSession,
+  type AgentSessionEvent,
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
+  type ResourceLoader,
 } from "@mariozechner/pi-coding-agent";
+import { type AssistantMessage, type Message, type ThinkingLevel as AiThinkingLevel } from "@mariozechner/pi-ai";
 import {
-  completeSimple,
-  streamSimple,
-  type AssistantMessage,
-  type Message,
-  type ThinkingLevel as AiThinkingLevel,
-} from "@mariozechner/pi-ai";
-import { Box, Text } from "@mariozechner/pi-tui";
+  Box,
+  Container,
+  Input,
+  Key,
+  Text,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Focusable,
+  type KeybindingsManager,
+  type OverlayHandle,
+  type TUI,
+} from "@mariozechner/pi-tui";
 
 const BTW_MESSAGE_TYPE = "btw-note";
 const BTW_ENTRY_TYPE = "btw-thread-entry";
 const BTW_RESET_TYPE = "btw-thread-reset";
+const BTW_FOCUS_SHORTCUTS = [Key.alt("/"), Key.ctrlAlt("w")] as const;
+
+function matchesBtwFocusShortcut(data: string): boolean {
+  return BTW_FOCUS_SHORTCUTS.some((shortcut) => matchesKey(data, shortcut));
+}
 
 const BTW_SYSTEM_PROMPT = [
   "You are having an aside conversation with the user, separate from their main working session.",
@@ -25,6 +45,12 @@ const BTW_SYSTEM_PROMPT = [
   "Do not act as if you need to continue unfinished work from the main session unless the user explicitly asks you to prepare something for injection back to it.",
 ].join(" ");
 
+const BTW_SUMMARIZE_SYSTEM_PROMPT =
+  "Summarize the side conversation concisely. Preserve key decisions, plans, insights, risks, and action items. Output only the summary.";
+
+const BTW_CONTINUE_THREAD_USER_TEXT = "[The following is a separate side conversation. Continue this thread.]";
+const BTW_CONTINUE_THREAD_ASSISTANT_TEXT = "Understood, continuing our side conversation.";
+
 type SessionThinkingLevel = "off" | AiThinkingLevel;
 type BtwThreadMode = "contextual" | "tangent";
 
@@ -51,13 +77,49 @@ type BtwResetDetails = {
   mode?: BtwThreadMode;
 };
 
-type BtwSlot = {
-  question: string;
-  modelLabel: string;
-  thinking: string;
-  answer: string;
-  done: boolean;
-  controller: AbortController;
+type BtwTranscriptEntry =
+  | { id: number; turnId: number; type: "turn-boundary"; phase: "start" | "end" }
+  | { id: number; turnId: number; type: "user-message"; text: string }
+  | { id: number; turnId: number; type: "thinking"; text: string; streaming: boolean }
+  | { id: number; turnId: number; type: "assistant-text"; text: string; streaming: boolean }
+  | { id: number; turnId: number; type: "tool-call"; toolCallId: string; toolName: string; args: string }
+  | {
+      id: number;
+      turnId: number;
+      type: "tool-result";
+      toolCallId: string;
+      toolName: string;
+      content: string;
+      truncated: boolean;
+      isError: boolean;
+      streaming: boolean;
+    };
+
+type BtwTranscript = BtwTranscriptEntry[];
+
+type BtwTranscriptState = {
+  entries: BtwTranscript;
+  nextEntryId: number;
+  nextTurnId: number;
+  currentTurnId: number | null;
+  lastTurnId: number | null;
+  toolCalls: Map<string, { turnId: number; callEntryId: number; resultEntryId?: number }>;
+};
+
+type BtwSessionRuntime = {
+  session: AgentSession;
+  mode: BtwThreadMode;
+  subscriptions: Set<() => void>;
+  sideThreadStartIndex: number;
+};
+
+type OverlayRuntime = {
+  handle?: OverlayHandle;
+  refresh?: () => void;
+  close?: () => void;
+  finish?: () => void;
+  setDraft?: (value: string) => void;
+  closed?: boolean;
 };
 
 function isVisibleBtwMessage(message: { role: string; customType?: string }): boolean {
@@ -68,8 +130,32 @@ function isCustomEntry(entry: unknown, customType: string): entry is { type: "cu
   return !!entry && typeof entry === "object" && (entry as { type?: string }).type === "custom" && (entry as { customType?: string }).customType === customType;
 }
 
-function toReasoning(level: SessionThinkingLevel): AiThinkingLevel | undefined {
-  return level === "off" ? undefined : level;
+function stripDynamicSystemPromptFooter(systemPrompt: string): string {
+  return systemPrompt
+    .replace(/\nCurrent date and time:[^\n]*(?:\nCurrent working directory:[^\n]*)?$/u, "")
+    .replace(/\nCurrent working directory:[^\n]*$/u, "")
+    .trim();
+}
+
+function createBtwResourceLoader(
+  ctx: ExtensionCommandContext,
+  appendSystemPrompt: string[] = [BTW_SYSTEM_PROMPT],
+): ResourceLoader {
+  const extensionsResult = { extensions: [], errors: [], runtime: createExtensionRuntime() };
+  const systemPrompt = stripDynamicSystemPromptFooter(ctx.getSystemPrompt());
+
+  return {
+    getExtensions: () => extensionsResult,
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    getSystemPrompt: () => systemPrompt,
+    getAppendSystemPrompt: () => appendSystemPrompt,
+    getPathMetadata: () => new Map(),
+    extendResources: () => {},
+    reload: async () => {},
+  };
 }
 
 function extractText(parts: AssistantMessage["content"], type: "text" | "thinking"): string {
@@ -100,29 +186,50 @@ function parseBtwArgs(args: string): ParsedBtwArgs {
   return { question, save };
 }
 
-function buildMainMessages(ctx: ExtensionCommandContext): Message[] {
-  const sessionContext = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
-  return sessionContext.messages.filter((message) => !isVisibleBtwMessage(message));
-}
-
-function buildBtwContext(
+function buildBtwSeedState(
   ctx: ExtensionCommandContext,
-  question: string,
   thread: BtwDetails[],
   mode: BtwThreadMode,
-) {
-  const messages: Message[] = mode === "contextual" ? [...buildMainMessages(ctx)] : [];
+): { messages: Message[]; sideThreadStartIndex: number } {
+  const messages: Message[] = [];
+
+  if (mode === "contextual") {
+    try {
+      messages.push(
+        ...buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages.filter(
+          (message) => !isVisibleBtwMessage(message),
+        ),
+      );
+    } catch {
+      messages.push(
+        ...ctx.sessionManager.getEntries().flatMap((entry) => {
+          if (!entry || typeof entry !== "object") {
+            return [];
+          }
+
+          const message = entry as Partial<Message> & { role?: string; customType?: string; content?: unknown };
+          if (typeof message.role !== "string" || !Array.isArray(message.content)) {
+            return [];
+          }
+
+          return isVisibleBtwMessage({ role: message.role, customType: message.customType }) ? [] : [message as Message];
+        }),
+      );
+    }
+  }
+
+  const sideThreadStartIndex = messages.length;
 
   if (thread.length > 0) {
     messages.push(
       {
         role: "user",
-        content: [{ type: "text", text: "[The following is a separate side conversation. Continue this thread.]" }],
+        content: [{ type: "text", text: BTW_CONTINUE_THREAD_USER_TEXT }],
         timestamp: Date.now(),
       },
       {
         role: "assistant",
-        content: [{ type: "text", text: "Understood, continuing our side conversation." }],
+        content: [{ type: "text", text: BTW_CONTINUE_THREAD_ASSISTANT_TEXT }],
         provider: ctx.model?.provider ?? "unknown",
         model: ctx.model?.id ?? "unknown",
         api: ctx.model?.api ?? "openai-responses",
@@ -168,159 +275,1366 @@ function buildBtwContext(
     }
   }
 
-  messages.push({
-    role: "user",
-    content: [{ type: "text", text: question }],
-    timestamp: Date.now(),
-  });
+  return {
+    messages,
+    sideThreadStartIndex,
+  };
+}
+
+function formatToolPreview(value: unknown): string {
+  if (value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value && typeof value === "object") {
+    const path = (value as { path?: unknown }).path;
+    if (typeof path === "string") {
+      return path;
+    }
+  }
+
+  try {
+    const preview = JSON.stringify(value);
+    if (!preview || preview === "{}") {
+      return "";
+    }
+    return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
+  } catch {
+    return "";
+  }
+}
+
+function createEmptyTranscriptState(): BtwTranscriptState {
+  return {
+    entries: [],
+    nextEntryId: 1,
+    nextTurnId: 1,
+    currentTurnId: null,
+    lastTurnId: null,
+    toolCalls: new Map(),
+  };
+}
+
+function appendTranscriptEntry<T extends BtwTranscriptEntry>(
+  state: BtwTranscriptState,
+  entry: Omit<T, "id">,
+): T {
+  const nextEntry = { ...entry, id: state.nextEntryId++ } as T;
+  state.entries.push(nextEntry);
+  return nextEntry;
+}
+
+function ensureTranscriptTurn(state: BtwTranscriptState): number {
+  if (state.currentTurnId !== null) {
+    return state.currentTurnId;
+  }
+
+  const turnId = state.nextTurnId++;
+  state.currentTurnId = turnId;
+  state.lastTurnId = turnId;
+  appendTranscriptEntry(state, { type: "turn-boundary", turnId, phase: "start" });
+  return turnId;
+}
+
+function finishTranscriptTurn(state: BtwTranscriptState, turnId?: number | null): void {
+  const resolvedTurnId = turnId ?? state.currentTurnId;
+  if (resolvedTurnId === null || resolvedTurnId === undefined) {
+    return;
+  }
+
+  const hasEndBoundary = state.entries.some(
+    (entry) => entry.turnId === resolvedTurnId && entry.type === "turn-boundary" && entry.phase === "end",
+  );
+  if (!hasEndBoundary) {
+    appendTranscriptEntry(state, { type: "turn-boundary", turnId: resolvedTurnId, phase: "end" });
+  }
+
+  for (const entry of state.entries) {
+    if (entry.turnId !== resolvedTurnId) {
+      continue;
+    }
+
+    if (entry.type === "thinking" || entry.type === "assistant-text" || entry.type === "tool-result") {
+      entry.streaming = false;
+    }
+  }
+
+  state.lastTurnId = resolvedTurnId;
+  if (state.currentTurnId === resolvedTurnId) {
+    state.currentTurnId = null;
+  }
+}
+
+function removeTranscriptTurn(state: BtwTranscriptState, turnId: number | null): void {
+  if (turnId === null) {
+    return;
+  }
+
+  state.entries = state.entries.filter((entry) => entry.turnId !== turnId);
+  for (const [toolCallId, toolCall] of state.toolCalls.entries()) {
+    if (toolCall.turnId === turnId) {
+      state.toolCalls.delete(toolCallId);
+    }
+  }
+
+  if (state.currentTurnId === turnId) {
+    state.currentTurnId = null;
+  }
+  if (state.lastTurnId === turnId) {
+    state.lastTurnId = null;
+  }
+}
+
+function findLatestTranscriptEntry<TType extends BtwTranscriptEntry["type"]>(
+  state: BtwTranscriptState,
+  turnId: number,
+  type: TType,
+): Extract<BtwTranscriptEntry, { type: TType }> | undefined {
+  for (let i = state.entries.length - 1; i >= 0; i--) {
+    const entry = state.entries[i];
+    if (entry.turnId === turnId && entry.type === type) {
+      return entry as Extract<BtwTranscriptEntry, { type: TType }>;
+    }
+  }
+
+  return undefined;
+}
+
+function ensureTranscriptTurnForUserMessage(state: BtwTranscriptState): number {
+  if (state.currentTurnId !== null) {
+    const currentAssistant = findLatestTranscriptEntry(state, state.currentTurnId, "assistant-text");
+    if (currentAssistant && !currentAssistant.streaming) {
+      finishTranscriptTurn(state, state.currentTurnId);
+    }
+  }
+
+  return ensureTranscriptTurn(state);
+}
+
+function extractMessageText(message: { content?: AssistantMessage["content"] }): string {
+  return Array.isArray(message.content) ? extractText(message.content, "text") : "";
+}
+
+function upsertUserMessageEntry(state: BtwTranscriptState, turnId: number, text: string): void {
+  if (!text) {
+    return;
+  }
+
+  const existing = findLatestTranscriptEntry(state, turnId, "user-message");
+  if (existing) {
+    existing.text = text;
+    return;
+  }
+
+  appendTranscriptEntry(state, { type: "user-message", turnId, text });
+}
+
+function upsertTranscriptTextEntry(
+  state: BtwTranscriptState,
+  turnId: number,
+  type: "thinking" | "assistant-text",
+  text: string,
+  streaming: boolean,
+): void {
+  if (!text) {
+    return;
+  }
+
+  const existing = findLatestTranscriptEntry(state, turnId, type);
+  if (existing) {
+    existing.text = text;
+    existing.streaming = streaming;
+    return;
+  }
+
+  appendTranscriptEntry(state, { type, turnId, text, streaming });
+}
+
+function summarizeToolResult(value: unknown, maxLength = 400): { content: string; truncated: boolean } {
+  let content = "";
+
+  if (value && typeof value === "object") {
+    const toolValue = value as {
+      content?: Array<{ type?: string; text?: string }>;
+      error?: unknown;
+      message?: unknown;
+    };
+
+    if (Array.isArray(toolValue.content)) {
+      content = toolValue.content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text ?? "")
+        .join("\n")
+        .trim();
+    }
+
+    if (!content && typeof toolValue.error === "string") {
+      content = toolValue.error;
+    }
+
+    if (!content && typeof toolValue.message === "string") {
+      content = toolValue.message;
+    }
+  }
+
+  if (!content) {
+    if (typeof value === "string") {
+      content = value;
+    } else if (value !== undefined) {
+      try {
+        content = JSON.stringify(value, null, 2);
+      } catch {
+        content = String(value);
+      }
+    }
+  }
+
+  if (!content) {
+    content = "(no tool output)";
+  }
+
+  const truncated = content.length > maxLength;
+  return {
+    content: truncated ? `${content.slice(0, maxLength - 3)}...` : content,
+    truncated,
+  };
+}
+
+function ensureToolCallEntry(
+  state: BtwTranscriptState,
+  turnId: number,
+  toolCallId: string,
+  toolName: string,
+  args: string,
+): { turnId: number; callEntryId: number; resultEntryId?: number } {
+  const existing = state.toolCalls.get(toolCallId);
+  if (existing) {
+    return existing;
+  }
+
+  const callEntry = appendTranscriptEntry(state, {
+    type: "tool-call",
+    turnId,
+    toolCallId,
+    toolName,
+    args,
+  });
+  const record = { turnId, callEntryId: callEntry.id };
+  state.toolCalls.set(toolCallId, record);
+  return record;
+}
+
+function upsertToolResultEntry(
+  state: BtwTranscriptState,
+  turnId: number,
+  toolCallId: string,
+  toolName: string,
+  content: string,
+  truncated: boolean,
+  isError: boolean,
+  streaming: boolean,
+): void {
+  const toolCall = ensureToolCallEntry(state, turnId, toolCallId, toolName, "");
+  const existing =
+    toolCall.resultEntryId !== undefined
+      ? state.entries.find((entry) => entry.id === toolCall.resultEntryId && entry.type === "tool-result")
+      : undefined;
+
+  if (existing && existing.type === "tool-result") {
+    existing.content = content;
+    existing.truncated = truncated;
+    existing.isError = isError;
+    existing.streaming = streaming;
+    return;
+  }
+
+  const resultEntry = appendTranscriptEntry(state, {
+    type: "tool-result",
+    turnId,
+    toolCallId,
+    toolName,
+    content,
+    truncated,
+    isError,
+    streaming,
+  });
+  toolCall.resultEntryId = resultEntry.id;
+}
+
+function applyAssistantMessageToTranscript(
+  state: BtwTranscriptState,
+  turnId: number,
+  message: AgentSessionEvent extends { message: infer T } ? T : never,
+  streaming: boolean,
+): void {
+  if (!message || typeof message !== "object" || (message as { role?: string }).role !== "assistant") {
+    return;
+  }
+
+  const assistantMessage = message as AssistantMessage;
+  const thinking = extractThinking(assistantMessage);
+  const answer = extractMessageText(assistantMessage);
+
+  if (thinking) {
+    upsertTranscriptTextEntry(state, turnId, "thinking", thinking, streaming);
+  }
+
+  if (answer) {
+    upsertTranscriptTextEntry(state, turnId, "assistant-text", answer, streaming);
+  }
+}
+
+function applyTranscriptEvent(state: BtwTranscriptState, event: AgentSessionEvent): void {
+  switch (event.type) {
+    case "turn_start": {
+      ensureTranscriptTurn(state);
+      return;
+    }
+    case "message_start": {
+      if (event.message.role === "user") {
+        const turnId = ensureTranscriptTurnForUserMessage(state);
+        upsertUserMessageEntry(state, turnId, extractMessageText(event.message));
+        return;
+      }
+
+      if (event.message.role === "assistant") {
+        const turnId = ensureTranscriptTurn(state);
+        applyAssistantMessageToTranscript(state, turnId, event.message, true);
+      }
+      return;
+    }
+    case "message_update": {
+      if (event.message.role !== "assistant") {
+        return;
+      }
+
+      const turnId = ensureTranscriptTurn(state);
+      applyAssistantMessageToTranscript(state, turnId, event.message, true);
+      return;
+    }
+    case "message_end": {
+      if (event.message.role === "user") {
+        const turnId = ensureTranscriptTurnForUserMessage(state);
+        upsertUserMessageEntry(state, turnId, extractMessageText(event.message));
+        return;
+      }
+
+      if (event.message.role === "assistant") {
+        const turnId = ensureTranscriptTurn(state);
+        applyAssistantMessageToTranscript(state, turnId, event.message, false);
+      }
+      return;
+    }
+    case "tool_execution_start": {
+      const turnId = ensureTranscriptTurn(state);
+      ensureToolCallEntry(state, turnId, event.toolCallId, event.toolName, formatToolPreview(event.args));
+      return;
+    }
+    case "tool_execution_update": {
+      const turnId = state.toolCalls.get(event.toolCallId)?.turnId ?? ensureTranscriptTurn(state);
+      const result = summarizeToolResult(event.partialResult);
+      upsertToolResultEntry(
+        state,
+        turnId,
+        event.toolCallId,
+        event.toolName,
+        result.content,
+        result.truncated,
+        false,
+        true,
+      );
+      return;
+    }
+    case "tool_execution_end": {
+      const turnId = state.toolCalls.get(event.toolCallId)?.turnId ?? ensureTranscriptTurn(state);
+      const result = summarizeToolResult(event.result);
+      upsertToolResultEntry(
+        state,
+        turnId,
+        event.toolCallId,
+        event.toolName,
+        result.content,
+        result.truncated,
+        event.isError,
+        false,
+      );
+      return;
+    }
+    case "turn_end": {
+      finishTranscriptTurn(state);
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+function appendPersistedTranscriptTurn(state: BtwTranscriptState, details: BtwDetails): void {
+  const turnId = ensureTranscriptTurn(state);
+  upsertUserMessageEntry(state, turnId, details.question);
+  if (details.thinking) {
+    upsertTranscriptTextEntry(state, turnId, "thinking", details.thinking, false);
+  }
+  upsertTranscriptTextEntry(state, turnId, "assistant-text", details.answer, false);
+  finishTranscriptTurn(state, turnId);
+}
+
+function setTranscriptFailure(state: BtwTranscriptState, message: string): void {
+  const turnId = state.currentTurnId ?? state.lastTurnId ?? ensureTranscriptTurn(state);
+  upsertTranscriptTextEntry(state, turnId, "assistant-text", `❌ ${message}`, false);
+  finishTranscriptTurn(state, turnId);
+}
+
+function hasStreamingTranscriptEntry(entries: BtwTranscript): boolean {
+  return entries.some(
+    (entry) =>
+      (entry.type === "thinking" || entry.type === "assistant-text" || entry.type === "tool-result") &&
+      entry.streaming,
+  );
+}
+
+function getCompletedExchangeCount(entries: BtwTranscript): number {
+  return entries.filter((entry) => entry.type === "assistant-text" && !entry.streaming).length;
+}
+
+function buildOverlayTranscript(entries: BtwTranscript, theme: ExtensionContext["ui"]["theme"]): string[] {
+  if (entries.length === 0) {
+    return [theme.fg("dim", "No BTW thread yet. Ask a side question to start one.")];
+  }
+
+  const lines: string[] = [];
+  const userBadge = buildTranscriptBadge(theme, "You", "userMessageBg", "accent");
+  const thinkingBadge = buildTranscriptBadge(theme, "Thinking", "toolPendingBg", "warning");
+  const toolBadge = buildTranscriptBadge(theme, "Tool", "toolPendingBg", "warning");
+  const assistantBadge = buildTranscriptBadge(theme, "Assistant", "customMessageBg", "success");
+  const separator = theme.fg("borderMuted", "────────────────────────────────────────");
+  const blockIndent = "    ";
+  const resultIndent = blockIndent;
+
+  const pushBlankLine = () => {
+    if (lines.length > 0 && lines[lines.length - 1] !== "") {
+      lines.push("");
+    }
+  };
+
+  const pushInlineBlock = (
+    header: string,
+    text: string,
+    options: { blankBefore?: boolean; style?: (value: string) => string } = {},
+  ) => {
+    const bodyLines = text.split("\n");
+    const style = options.style ?? ((value: string) => value);
+    if (options.blankBefore !== false) {
+      pushBlankLine();
+    }
+
+    const firstLine = bodyLines.shift() ?? "";
+    lines.push(`${header}${firstLine ? ` ${style(firstLine)}` : ""}`);
+    for (const line of bodyLines) {
+      lines.push(`${blockIndent}${style(line)}`);
+    }
+  };
+
+  const pushStackedBlock = (
+    header: string,
+    text: string,
+    options: { blankBefore?: boolean; indent?: string; style?: (value: string) => string } = {},
+  ) => {
+    const bodyLines = text.split("\n");
+    const indent = options.indent ?? blockIndent;
+    const style = options.style ?? ((value: string) => value);
+    if (options.blankBefore !== false) {
+      pushBlankLine();
+    }
+
+    lines.push(header);
+    for (const line of bodyLines) {
+      lines.push(`${indent}${style(line)}`);
+    }
+  };
+
+  for (const entry of entries) {
+    if (entry.type === "turn-boundary") {
+      if (entry.phase === "start" && lines.length > 0) {
+        pushBlankLine();
+        lines.push(separator);
+      }
+      continue;
+    }
+
+    if (entry.type === "user-message") {
+      pushInlineBlock(userBadge, entry.text, { blankBefore: false });
+      continue;
+    }
+
+    if (entry.type === "thinking") {
+      const thinkingHeader = entry.streaming ? `${thinkingBadge} ${theme.fg("warning", "▍")}` : thinkingBadge;
+      pushStackedBlock(thinkingHeader, entry.text, {
+        style: (line) => theme.fg("warning", theme.italic(line)),
+      });
+      continue;
+    }
+
+    if (entry.type === "tool-call") {
+      const toolLabel = theme.fg("warning", theme.bold(entry.toolName));
+      const argsLabel = entry.args ? theme.fg("dim", ` · ${entry.args}`) : "";
+      pushInlineBlock(toolBadge, `${toolLabel}${argsLabel}`);
+      continue;
+    }
+
+    if (entry.type === "tool-result") {
+      const resultHeaderLabel = entry.isError
+        ? theme.fg("error", "↳ error")
+        : entry.streaming
+          ? theme.fg("warning", "↳ streaming result")
+          : theme.fg("dim", "↳ result");
+      const truncationLabel = entry.truncated ? theme.fg("dim", " (truncated)") : "";
+      pushStackedBlock(`${resultHeaderLabel}${truncationLabel}`, entry.content, {
+        blankBefore: false,
+        indent: resultIndent,
+        style: (line) => (entry.isError ? theme.fg("error", line) : theme.fg("dim", line)),
+      });
+      continue;
+    }
+
+    if (entry.type === "assistant-text") {
+      const assistantHeader = entry.streaming ? `${assistantBadge} ${theme.fg("warning", "▍")}` : assistantBadge;
+      pushStackedBlock(assistantHeader, entry.text);
+    }
+  }
+
+  return lines;
+}
+
+function getLastAssistantMessage(session: AgentSession): AssistantMessage | null {
+  for (let i = session.state.messages.length - 1; i >= 0; i--) {
+    const message = session.state.messages[i];
+    if (message.role === "assistant") {
+      return message as AssistantMessage;
+    }
+  }
+
+  return null;
+}
+
+type BtwHandoffExchange = {
+  user: string;
+  assistant: string;
+};
+
+function buildBtwMessageContent(question: string, answer: string): string {
+  return `Q: ${question}\n\nA: ${answer}`;
+}
+
+function formatThread(thread: BtwHandoffExchange[]): string {
+  return thread.map((entry) => `User: ${entry.user.trim()}\nAssistant: ${entry.assistant.trim()}`).join("\n\n---\n\n");
+}
+
+function isThreadContinuationMarker(messages: Message[], index: number): boolean {
+  const userMessage = messages[index];
+  const assistantMessage = messages[index + 1];
+  return (
+    userMessage?.role === "user" &&
+    extractMessageText(userMessage) === BTW_CONTINUE_THREAD_USER_TEXT &&
+    assistantMessage?.role === "assistant" &&
+    extractMessageText(assistantMessage) === BTW_CONTINUE_THREAD_ASSISTANT_TEXT
+  );
+}
+
+function extractBtwHandoffThread(sessionRuntime: BtwSessionRuntime): BtwHandoffExchange[] {
+  const handoffMessages = sessionRuntime.session.state.messages.slice(sessionRuntime.sideThreadStartIndex);
+  const threadMessages = isThreadContinuationMarker(handoffMessages, 0) ? handoffMessages.slice(2) : handoffMessages;
+  const exchanges: BtwHandoffExchange[] = [];
+  let currentUser = "";
+  let currentAssistant = "";
+
+  const pushCurrent = () => {
+    if (!currentUser && !currentAssistant) {
+      return;
+    }
+
+    exchanges.push({
+      user: currentUser.trim() || "(No user prompt)",
+      assistant: currentAssistant.trim() || "(No assistant response)",
+    });
+    currentUser = "";
+    currentAssistant = "";
+  };
+
+  for (const message of threadMessages) {
+    if (message.role !== "user" && message.role !== "assistant") {
+      continue;
+    }
+
+    const text = extractMessageText(message).trim();
+    if (!text) {
+      continue;
+    }
+
+    if (message.role === "user") {
+      pushCurrent();
+      currentUser = text;
+      continue;
+    }
+
+    currentAssistant = currentAssistant ? `${currentAssistant}\n\n${text}` : text;
+  }
+
+  pushCurrent();
+  return exchanges;
+}
+
+function saveVisibleBtwNote(
+  pi: ExtensionAPI,
+  details: BtwDetails,
+  saveRequested: boolean,
+  wasBusy: boolean,
+): SaveState {
+  if (!saveRequested) {
+    return "not-saved";
+  }
+
+  const message = {
+    customType: BTW_MESSAGE_TYPE,
+    content: buildBtwMessageContent(details.question, details.answer),
+    display: true,
+    details,
+  };
+
+  if (wasBusy) {
+    pi.sendMessage(message, { deliverAs: "followUp" });
+    return "queued";
+  }
+
+  pi.sendMessage(message);
+  return "saved";
+}
+
+function notify(ctx: ExtensionContext | ExtensionCommandContext, message: string, level: "info" | "warning" | "error"): void {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, level);
+  }
+}
+
+function getOverlayTitle(mode: BtwThreadMode): string {
+  return mode === "tangent" ? "BTW tangent" : "BTW";
+}
+
+function buildTranscriptBadge(
+  theme: ExtensionContext["ui"]["theme"],
+  label: string,
+  background: string,
+  foreground: string,
+): string {
+  return theme.bg(background, theme.fg(foreground, theme.bold(` ${label} `)));
+}
+
+class BtwOverlayComponent extends Container implements Focusable {
+  private readonly input: Input;
+  private readonly transcript: Container;
+  private readonly statusText: Text;
+  private readonly modeText: Text;
+  private readonly summaryText: Text;
+  private readonly hintsText: Text;
+  private readonly readTranscriptEntries: () => BtwTranscript;
+  private readonly getStatus: () => string | null;
+  private readonly getMode: () => BtwThreadMode;
+  private readonly onSubmitCallback: (value: string) => void;
+  private readonly onDismissCallback: () => void;
+  private readonly onUnfocusCallback: () => void;
+  private readonly tui: TUI;
+  private readonly theme: ExtensionContext["ui"]["theme"];
+  private transcriptLines: string[] = [];
+  private transcriptScrollOffset = 0;
+  private transcriptViewportHeight = 8;
+  private followTranscript = true;
+  private _focused = false;
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value;
+  }
+
+  constructor(
+    tui: TUI,
+    theme: ExtensionContext["ui"]["theme"],
+    keybindings: KeybindingsManager,
+    readTranscriptEntries: () => BtwTranscript,
+    getStatus: () => string | null,
+    getMode: () => BtwThreadMode,
+    onSubmit: (value: string) => void,
+    onDismiss: () => void,
+    onUnfocus: () => void,
+  ) {
+    super();
+    this.tui = tui;
+    this.theme = theme;
+    this.readTranscriptEntries = readTranscriptEntries;
+    this.getStatus = getStatus;
+    this.getMode = getMode;
+    this.onSubmitCallback = onSubmit;
+    this.onDismissCallback = onDismiss;
+    this.onUnfocusCallback = onUnfocus;
+
+    this.modeText = new Text("", 1, 0);
+    this.summaryText = new Text("", 1, 0);
+    this.transcript = new Container();
+    this.statusText = new Text("", 1, 0);
+
+    this.input = new Input();
+    this.input.onSubmit = (value) => {
+      this.followTranscript = true;
+      this.onSubmitCallback(value);
+    };
+    this.input.onEscape = () => {
+      this.onDismissCallback();
+    };
+
+    this.hintsText = new Text("", 1, 0);
+
+    const originalHandleInput = this.input.handleInput.bind(this.input);
+    this.input.handleInput = (data: string) => {
+      if (keybindings.matches(data, "selectCancel")) {
+        this.onDismissCallback();
+        return;
+      }
+      originalHandleInput(data);
+    };
+
+    this.refresh();
+  }
+
+  private frameLine(content: string, innerWidth: number): string {
+    const truncated = truncateToWidth(content, innerWidth, "");
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return `${this.theme.fg("borderMuted", "│")}${truncated}${" ".repeat(padding)}${this.theme.fg("borderMuted", "│")}`;
+  }
+
+  private ruleLine(innerWidth: number): string {
+    return this.theme.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`);
+  }
+
+  private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
+    const left = edge === "top" ? "┌" : "└";
+    const right = edge === "top" ? "┐" : "┘";
+    return this.theme.fg("borderMuted", `${left}${"─".repeat(innerWidth)}${right}`);
+  }
+
+  private wrapTranscript(innerWidth: number): string[] {
+    const wrapped: string[] = [];
+    for (const line of this.transcriptLines) {
+      if (!line) {
+        wrapped.push("");
+        continue;
+      }
+      wrapped.push(...wrapTextWithAnsi(line, Math.max(1, innerWidth)));
+    }
+    return wrapped;
+  }
+
+  private getDialogHeight(): number {
+    const terminalRows = process.stdout.rows ?? 30;
+    return Math.max(18, Math.min(32, Math.floor(terminalRows * 0.78)));
+  }
+
+  handleInput(data: string): void {
+    if (matchesBtwFocusShortcut(data)) {
+      this.onUnfocusCallback();
+      return;
+    }
+
+    if (matchesKey(data, Key.pageUp)) {
+      this.followTranscript = false;
+      this.transcriptScrollOffset = Math.max(0, this.transcriptScrollOffset - Math.max(1, this.transcriptViewportHeight - 1));
+      this.tui.requestRender();
+      return;
+    }
+
+    if (matchesKey(data, Key.pageDown)) {
+      this.transcriptScrollOffset += Math.max(1, this.transcriptViewportHeight - 1);
+      this.tui.requestRender();
+      return;
+    }
+
+    this.input.handleInput(data);
+  }
+
+  private inputFrameLine(dialogWidth: number): string {
+    const targetWidth = Math.max(1, dialogWidth - 2);
+    const previousFocused = this.input.focused;
+    // Input.render() emits CURSOR_MARKER when focused. In overlay mode that APC marker
+    // can skew width/composition on this one row before the TUI strips it, producing a
+    // right-edge notch and shifted border. Render the embedded input unfocused here so
+    // the row stays geometrically stable while the overlay still owns keyboard input.
+    this.input.focused = false;
+    try {
+      const inputLine = this.input.render(targetWidth)[0] ?? "";
+      return `${this.theme.fg("borderMuted", "│")}${inputLine}${this.theme.fg("borderMuted", "│")}`;
+    } finally {
+      this.input.focused = previousFocused;
+    }
+  }
+
+  override render(width: number): string[] {
+    const dialogWidth = Math.max(24, width);
+    const innerWidth = Math.max(22, dialogWidth - 2);
+    const transcriptLines = this.wrapTranscript(innerWidth);
+    const dialogHeight = this.getDialogHeight();
+    const chromeHeight = 8;
+    const transcriptHeight = Math.max(6, dialogHeight - chromeHeight);
+    this.transcriptViewportHeight = transcriptHeight;
+
+    const maxScroll = Math.max(0, transcriptLines.length - transcriptHeight);
+    if (this.followTranscript) {
+      this.transcriptScrollOffset = maxScroll;
+    } else {
+      this.transcriptScrollOffset = Math.max(0, Math.min(this.transcriptScrollOffset, maxScroll));
+      if (this.transcriptScrollOffset >= maxScroll) {
+        this.followTranscript = true;
+      }
+    }
+
+    const visibleTranscript = transcriptLines.slice(
+      this.transcriptScrollOffset,
+      this.transcriptScrollOffset + transcriptHeight,
+    );
+    const transcriptPadCount = Math.max(0, transcriptHeight - visibleTranscript.length);
+    const hiddenAbove = this.transcriptScrollOffset;
+    const hiddenBelow = Math.max(0, maxScroll - this.transcriptScrollOffset);
+    const summary =
+      hiddenAbove || hiddenBelow
+        ? `${this.summaryText.text.trim()} · ↑${hiddenAbove} ↓${hiddenBelow}`
+        : this.summaryText.text.trim();
+
+    const lines = [this.borderLine(innerWidth, "top")];
+
+    lines.push(this.frameLine(this.theme.fg("accent", this.theme.bold(this.modeText.text.trim())), innerWidth));
+    lines.push(this.frameLine(this.theme.fg("dim", summary), innerWidth));
+    lines.push(this.ruleLine(innerWidth));
+
+    for (const line of visibleTranscript) {
+      lines.push(this.frameLine(line, innerWidth));
+    }
+    for (let i = 0; i < transcriptPadCount; i++) {
+      lines.push(this.frameLine("", innerWidth));
+    }
+
+    lines.push(this.ruleLine(innerWidth));
+    lines.push(this.frameLine(this.theme.fg("warning", this.statusText.text.trim()), innerWidth));
+    lines.push(this.inputFrameLine(dialogWidth));
+    lines.push(this.frameLine(this.theme.fg("dim", this.hintsText.text.trim()), innerWidth));
+    lines.push(this.borderLine(innerWidth, "bottom"));
+
+    return lines;
+  }
+
+  setDraft(value: string): void {
+    this.input.setValue(value);
+    this.tui.requestRender();
+  }
+
+  getDraft(): string {
+    return this.input.getValue();
+  }
+
+  getTranscriptEntries(): BtwTranscript {
+    return this.readTranscriptEntries().map((entry) => ({ ...entry }));
+  }
+
+  refresh(): void {
+    this.modeText.setText(`${getOverlayTitle(this.getMode())} · hidden thread preserved`);
+    const entries = this.readTranscriptEntries();
+    const exchanges = getCompletedExchangeCount(entries);
+    const active = hasStreamingTranscriptEntry(entries) ? " · streaming" : " · idle";
+    this.summaryText.setText(`${exchanges} exchange${exchanges === 1 ? "" : "s"}${active}`);
+
+    this.transcriptLines = buildOverlayTranscript(entries, this.theme);
+    this.transcript.clear();
+    for (const line of this.transcriptLines) {
+      this.transcript.addChild(new Text(line, 1, 0));
+    }
+
+    const status = this.getStatus() ?? "Ready. Enter submits; Escape dismisses without clearing.";
+    this.statusText.setText(status);
+    this.hintsText.setText("Enter submit · Alt+/ toggle focus · Escape dismiss · PgUp/PgDn scroll");
+    this.tui.requestRender();
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  let pendingThread: BtwDetails[] = [];
+  let pendingMode: BtwThreadMode = "contextual";
+  let transcriptState = createEmptyTranscriptState();
+  let overlayStatus: string | null = null;
+  let overlayDraft = "";
+  let overlayRuntime: OverlayRuntime | null = null;
+  let lastUiContext: ExtensionContext | ExtensionCommandContext | null = null;
+  let activeBtwSession: BtwSessionRuntime | null = null;
+
+  function syncUi(ctx?: ExtensionContext | ExtensionCommandContext): void {
+    const activeCtx = ctx ?? lastUiContext;
+    if (activeCtx?.hasUI) {
+      activeCtx.ui.setWidget("btw", undefined);
+      overlayRuntime?.refresh?.();
+    }
+  }
+
+  function setOverlayStatus(status: string | null, ctx?: ExtensionContext | ExtensionCommandContext): void {
+    overlayStatus = status;
+    syncUi(ctx);
+  }
+
+  function setOverlayDraft(value: string): void {
+    overlayDraft = value;
+    overlayRuntime?.setDraft?.(value);
+  }
+
+  function dismissOverlay(): void {
+    overlayRuntime?.close?.();
+    overlayRuntime = null;
+  }
+
+  function toggleOverlayFocus(): void {
+    const handle = overlayRuntime?.handle;
+    if (!handle) {
+      return;
+    }
+
+    handle.setHidden(false);
+    if (handle.isFocused()) {
+      handle.unfocus();
+    } else {
+      handle.focus();
+    }
+    overlayRuntime?.refresh?.();
+  }
+
+  function focusOverlay(): void {
+    const handle = overlayRuntime?.handle;
+    if (!handle) {
+      return;
+    }
+
+    handle.setHidden(false);
+    handle.focus();
+    overlayRuntime?.refresh?.();
+  }
+
+  function removeBtwSessionSubscription(sessionRuntime: BtwSessionRuntime, unsubscribe: () => void): void {
+    if (!sessionRuntime.subscriptions.delete(unsubscribe)) {
+      return;
+    }
+
+    try {
+      unsubscribe();
+    } catch {
+      // Ignore unsubscribe errors during BTW session replacement/shutdown.
+    }
+  }
+
+  function clearBtwSessionSubscriptions(sessionRuntime: BtwSessionRuntime): void {
+    for (const unsubscribe of [...sessionRuntime.subscriptions]) {
+      removeBtwSessionSubscription(sessionRuntime, unsubscribe);
+    }
+  }
+
+  function handleBtwSessionEvent(
+    sessionRuntime: BtwSessionRuntime,
+    event: AgentSessionEvent,
+    ctx?: ExtensionContext | ExtensionCommandContext,
+  ): void {
+    if (activeBtwSession?.session !== sessionRuntime.session || !overlayRuntime) {
+      return;
+    }
 
-  return {
-    systemPrompt: [ctx.getSystemPrompt(), BTW_SYSTEM_PROMPT].filter(Boolean).join("\n\n"),
-    messages,
-  };
-}
+    applyTranscriptEvent(transcriptState, event);
 
-function buildBtwMessageContent(question: string, answer: string): string {
-  return `Q: ${question}\n\nA: ${answer}`;
-}
+    if (event.type === "tool_execution_start") {
+      setOverlayStatus(`⏳ running tool: ${event.toolName}`, ctx);
+      return;
+    }
 
-function formatThread(thread: BtwDetails[]): string {
-  return thread.map((entry) => `User: ${entry.question.trim()}\nAssistant: ${entry.answer.trim()}`).join("\n\n---\n\n");
-}
+    if (event.type === "tool_execution_end") {
+      setOverlayStatus(sessionRuntime.session.isStreaming ? `⏳ running tool: ${event.toolName}` : "⏳ streaming...", ctx);
+      return;
+    }
 
-function saveVisibleBtwNote(
-  pi: ExtensionAPI,
-  details: BtwDetails,
-  saveRequested: boolean,
-  wasBusy: boolean,
-): SaveState {
-  if (!saveRequested) {
-    return "not-saved";
+    if (event.type === "turn_end") {
+      setOverlayStatus("⏳ streaming...", ctx);
+      return;
+    }
+
+    if (
+      event.type === "message_start" ||
+      event.type === "message_update" ||
+      event.type === "message_end" ||
+      event.type === "turn_start"
+    ) {
+      syncUi(ctx);
+    }
   }
 
-  const message = {
-    customType: BTW_MESSAGE_TYPE,
-    content: buildBtwMessageContent(details.question, details.answer),
-    display: true,
-    details,
-  };
+  function subscribeOverlayToActiveBtwSession(ctx?: ExtensionContext | ExtensionCommandContext): void {
+    const sessionRuntime = activeBtwSession;
+    if (!sessionRuntime || sessionRuntime.subscriptions.size > 0) {
+      return;
+    }
 
-  if (wasBusy) {
-    pi.sendMessage(message, { deliverAs: "followUp" });
-    return "queued";
+    const unsubscribe = sessionRuntime.session.subscribe((event: AgentSessionEvent) => {
+      handleBtwSessionEvent(sessionRuntime, event, ctx);
+    });
+    sessionRuntime.subscriptions.add(unsubscribe);
   }
 
-  pi.sendMessage(message);
-  return "saved";
-}
+  async function disposeBtwSession(): Promise<void> {
+    const current = activeBtwSession;
+    activeBtwSession = null;
+    if (!current) {
+      return;
+    }
 
-function notify(ctx: ExtensionContext | ExtensionCommandContext, message: string, level: "info" | "warning" | "error"): void {
-  if (ctx.hasUI) {
-    ctx.ui.notify(message, level);
+    clearBtwSessionSubscriptions(current);
+
+    try {
+      await current.session.abort();
+    } catch {
+      // Ignore abort errors during BTW session replacement/shutdown.
+    }
+
+    current.session.dispose();
   }
-}
 
-export default function (pi: ExtensionAPI) {
-  let pendingThread: BtwDetails[] = [];
-  let pendingMode: BtwThreadMode = "contextual";
-  let slots: BtwSlot[] = [];
-  let widgetStatus: string | null = null;
+  async function dismissOverlaySession(): Promise<void> {
+    dismissOverlay();
+    await disposeBtwSession();
+  }
 
-  function abortActiveSlots(): void {
-    for (const slot of slots) {
-      if (!slot.done) {
-        slot.controller.abort();
-      }
+  async function createBtwSubSession(ctx: ExtensionCommandContext, mode: BtwThreadMode): Promise<BtwSessionRuntime> {
+    const { session } = await createAgentSession({
+      sessionManager: SessionManager.inMemory(),
+      model: ctx.model,
+      modelRegistry: ctx.modelRegistry as AgentSession["modelRegistry"],
+      thinkingLevel: pi.getThinkingLevel() as SessionThinkingLevel,
+      tools: codingTools,
+      resourceLoader: createBtwResourceLoader(ctx),
+    });
+
+    const { messages: seedMessages, sideThreadStartIndex } = buildBtwSeedState(ctx, pendingThread, mode);
+    if (seedMessages.length > 0) {
+      session.agent.replaceMessages(seedMessages as typeof session.state.messages);
+    }
+
+    return { session, mode, subscriptions: new Set(), sideThreadStartIndex };
+  }
+
+  async function ensureBtwSession(ctx: ExtensionCommandContext, mode: BtwThreadMode): Promise<BtwSessionRuntime | null> {
+    if (!ctx.model) {
+      return null;
+    }
+
+    if (activeBtwSession?.mode === mode) {
+      return activeBtwSession;
     }
+
+    await disposeBtwSession();
+    activeBtwSession = await createBtwSubSession(ctx, mode);
+    return activeBtwSession;
   }
 
-  function renderWidget(ctx: ExtensionContext | ExtensionCommandContext): void {
+  async function ensureOverlay(ctx: ExtensionCommandContext | ExtensionContext): Promise<void> {
     if (!ctx.hasUI) {
       return;
     }
+    lastUiContext = ctx;
 
-    if (slots.length === 0) {
-      ctx.ui.setWidget("btw", undefined);
+    if (overlayRuntime?.handle) {
+      subscribeOverlayToActiveBtwSession(ctx);
+      focusOverlay();
       return;
     }
 
-    ctx.ui.setWidget(
-      "btw",
-      (_tui, theme) => {
-        const dim = (text: string) => theme.fg("dim", text);
-        const success = (text: string) => theme.fg("success", text);
-        const italic = (text: string) => theme.fg("dim", theme.italic(text));
-        const warning = (text: string) => theme.fg("warning", text);
-        const parts: string[] = [];
-
-        const title = pendingMode === "tangent" ? " 💭 btw:tangent " : " 💭 btw ";
-        const hint = " /btw:clear dismiss · /btw:inject send ";
-        const width = Math.max(22, 68 - title.length - hint.length);
-        parts.push(dim(`╭${title}${"─".repeat(width)}${hint}╮`));
-
-        for (let i = 0; i < slots.length; i++) {
-          const slot = slots[i];
-          if (i > 0) {
-            parts.push(dim("│ ───"));
-          }
-
-          parts.push(dim("│ ") + success("› ") + slot.question);
+    const runtime: OverlayRuntime = {};
+    const closeRuntime = () => {
+      if (runtime.closed) {
+        return;
+      }
+      runtime.closed = true;
+      if (activeBtwSession) {
+        clearBtwSessionSubscriptions(activeBtwSession);
+      }
+      runtime.handle?.hide();
+      if (overlayRuntime === runtime) {
+        overlayRuntime = null;
+      }
+      runtime.finish?.();
+    };
 
-          if (slot.thinking) {
-            const cursor = !slot.answer && !slot.done ? warning(" ▍") : "";
-            parts.push(dim("│ ") + italic(slot.thinking) + cursor);
+    runtime.close = closeRuntime;
+    overlayRuntime = runtime;
+
+    void ctx.ui
+      .custom<void>(
+        async (tui, theme, keybindings, done) => {
+          runtime.finish = () => {
+            done();
+          };
+
+          const overlay = new BtwOverlayComponent(
+            tui,
+            theme,
+            keybindings,
+            () => transcriptState.entries,
+            () => overlayStatus,
+            () => pendingMode,
+            (value) => {
+              void submitFromOverlay(ctx, value);
+            },
+            () => {
+              void dismissOverlaySession();
+            },
+            () => {
+              overlayRuntime?.handle?.unfocus();
+              overlayRuntime?.refresh?.();
+            },
+          );
+
+          overlay.focused = runtime.handle?.isFocused() ?? true;
+          overlay.setDraft(overlayDraft);
+          runtime.setDraft = (value) => {
+            overlay.setDraft(value);
+          };
+          runtime.refresh = () => {
+            overlay.focused = runtime.handle?.isFocused() ?? false;
+            overlay.refresh();
+          };
+          runtime.close = () => {
+            overlayDraft = overlay.getDraft();
+            closeRuntime();
+          };
+
+          subscribeOverlayToActiveBtwSession(ctx);
+
+          if (runtime.closed) {
+            done();
           }
 
-          if (slot.answer) {
-            const answerLines = slot.answer.split("\n");
-            parts.push(dim("│ ") + answerLines[0]);
-            if (answerLines.length > 1) {
-              parts.push(answerLines.slice(1).join("\n"));
-            }
-            if (!slot.done) {
-              parts[parts.length - 1] += warning(" ▍");
+          return overlay;
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "78%",
+            minWidth: 72,
+            maxHeight: "78%",
+            anchor: "top-center",
+            margin: { top: 1, left: 2, right: 2 },
+            nonCapturing: true,
+          },
+          onHandle: (handle) => {
+            runtime.handle = handle;
+            handle.focus();
+            if (runtime.closed) {
+              closeRuntime();
             }
-          } else if (!slot.done) {
-            parts.push(dim("│ ") + warning("⏳ thinking..."));
-          }
-
-          parts.push(dim("│ ") + dim(`model: ${slot.modelLabel}`));
+          },
+        },
+      )
+      .catch((error) => {
+        if (overlayRuntime === runtime) {
+          overlayRuntime = null;
         }
+        notify(ctx, error instanceof Error ? error.message : String(error), "error");
+      });
+  }
 
-        if (widgetStatus) {
-          parts.push(dim("│ ") + warning(widgetStatus));
-        }
+  async function dispatchBtwCommand(name: string, args: string, ctx: ExtensionCommandContext): Promise<boolean> {
+    const trimmedArgs = args.trim();
 
-        parts.push(dim(`╰${"─".repeat(68)}╯`));
-        return new Text(parts.join("\n"), 0, 0);
-      },
-      { placement: "aboveEditor" },
-    );
+    if (name === "btw") {
+      const { question, save } = parseBtwArgs(trimmedArgs);
+      if (!question) {
+        await ensureBtwSession(ctx, pendingMode);
+        await ensureOverlay(ctx);
+        return true;
+      }
+
+      if (pendingMode !== "contextual") {
+        await resetThread(ctx, true, "contextual");
+      }
+
+      await runBtw(ctx, question, save, "contextual");
+      return true;
+    }
+
+    if (name === "btw:tangent") {
+      const { question, save } = parseBtwArgs(trimmedArgs);
+      if (pendingMode !== "tangent") {
+        await resetThread(ctx, true, "tangent");
+      }
+
+      if (!question) {
+        await ensureBtwSession(ctx, "tangent");
+        await ensureOverlay(ctx);
+        return true;
+      }
+
+      await runBtw(ctx, question, save, "tangent");
+      return true;
+    }
+
+    if (name === "btw:new") {
+      await resetThread(ctx, true, "contextual");
+      const { question, save } = parseBtwArgs(trimmedArgs);
+      if (question) {
+        await runBtw(ctx, question, save, "contextual");
+      } else {
+        await ensureBtwSession(ctx, "contextual");
+        setOverlayStatus("Started a fresh BTW thread.", ctx);
+        await ensureOverlay(ctx);
+        notify(ctx, "Started a fresh BTW thread.", "info");
+      }
+      return true;
+    }
+
+    if (name === "btw:clear") {
+      await resetThread(ctx);
+      dismissOverlay();
+      notify(ctx, "Cleared BTW thread.", "info");
+      return true;
+    }
+
+    if (name === "btw:inject") {
+      if (pendingThread.length === 0) {
+        notify(ctx, "No BTW thread to inject.", "warning");
+        return true;
+      }
+
+      setOverlayStatus("⏳ injecting into the main session...", ctx);
+      await ensureOverlay(ctx);
+
+      try {
+        const { thread } = await getBtwHandoffThread(ctx);
+        const instructions = trimmedArgs;
+        const content = instructions
+          ? `Here is a side conversation I had. ${instructions}\n\n${formatThread(thread)}`
+          : `Here is a side conversation I had for additional context:\n\n${formatThread(thread)}`;
+
+        sendThreadToMain(ctx, content);
+        const count = thread.length;
+        await resetThread(ctx);
+        dismissOverlay();
+        notify(ctx, `Injected BTW thread (${count} exchange${count === 1 ? "" : "s"}).`, "info");
+      } catch (error) {
+        setOverlayStatus("Inject failed. Thread preserved for retry or summarize.", ctx);
+        notify(ctx, error instanceof Error ? error.message : String(error), "error");
+      }
+      return true;
+    }
+
+    if (name === "btw:summarize") {
+      if (pendingThread.length === 0) {
+        notify(ctx, "No BTW thread to summarize.", "warning");
+        return true;
+      }
+
+      setOverlayStatus("⏳ summarizing...", ctx);
+      await ensureOverlay(ctx);
+
+      try {
+        const { thread } = await getBtwHandoffThread(ctx);
+        const summary = await summarizeThread(ctx, thread);
+        const instructions = trimmedArgs;
+        const content = instructions
+          ? `Here is a summary of a side conversation I had. ${instructions}\n\n${summary}`
+          : `Here is a summary of a side conversation I had:\n\n${summary}`;
+
+        sendThreadToMain(ctx, content);
+        const count = thread.length;
+        await resetThread(ctx);
+        dismissOverlay();
+        notify(ctx, `Injected BTW summary (${count} exchange${count === 1 ? "" : "s"}).`, "info");
+      } catch (error) {
+        setOverlayStatus("Summarize failed. Thread preserved for retry or injection.", ctx);
+        notify(ctx, error instanceof Error ? error.message : String(error), "error");
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  function parseOverlayBtwCommand(value: string): { name: string; args: string } | null {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^\/(btw:(?:new|tangent|clear|inject|summarize))(?:\s+(.*))?$/);
+    if (!match) {
+      return null;
+    }
+
+    return {
+      name: match[1],
+      args: match[2]?.trim() ?? "",
+    };
+  }
+
+  async function submitFromOverlay(ctx: ExtensionCommandContext | ExtensionContext, value: string): Promise<void> {
+    const question = value.trim();
+    if (!question) {
+      setOverlayStatus("Enter a BTW prompt before submitting.", ctx);
+      return;
+    }
+
+    if (!("getSystemPrompt" in ctx)) {
+      setOverlayStatus("BTW overlay submit requires a command context. Reopen BTW from a command.", ctx);
+      return;
+    }
+
+    const btwCommand = parseOverlayBtwCommand(question);
+    if (btwCommand) {
+      setOverlayDraft("");
+      await dispatchBtwCommand(btwCommand.name, btwCommand.args, ctx);
+      return;
+    }
+
+    setOverlayDraft("");
+    setOverlayStatus("⏳ streaming...", ctx);
+    syncUi(ctx);
+    await runBtw(ctx, question, false, pendingMode);
   }
 
-  function resetThread(
+  async function resetThread(
     ctx: ExtensionContext | ExtensionCommandContext,
     persist = true,
     mode: BtwThreadMode = "contextual",
-  ): void {
-    abortActiveSlots();
+  ): Promise<void> {
+    await disposeBtwSession();
     pendingThread = [];
     pendingMode = mode;
-    slots = [];
-    widgetStatus = null;
+    transcriptState = createEmptyTranscriptState();
+    setOverlayDraft("");
+    setOverlayStatus(null, ctx);
     if (persist) {
       const details: BtwResetDetails = { timestamp: Date.now(), mode };
       pi.appendEntry(BTW_RESET_TYPE, details);
     }
-    renderWidget(ctx);
+    syncUi(ctx);
   }
 
-  function restoreThread(ctx: ExtensionContext): void {
-    abortActiveSlots();
+  async function restoreThread(ctx: ExtensionContext): Promise<void> {
+    await disposeBtwSession();
     pendingThread = [];
     pendingMode = "contextual";
-    slots = [];
-    widgetStatus = null;
+    transcriptState = createEmptyTranscriptState();
+    overlayDraft = "";
+    lastUiContext = ctx;
+    overlayStatus = null;
 
     const branch = ctx.sessionManager.getBranch();
     let lastResetIndex = -1;
@@ -344,17 +1658,10 @@ export default function (pi: ExtensionAPI) {
       }
 
       pendingThread.push(details);
-      slots.push({
-        question: details.question,
-        modelLabel: `${details.provider}/${details.model}`,
-        thinking: details.thinking || "",
-        answer: details.answer,
-        done: true,
-        controller: new AbortController(),
-      });
+      appendPersistedTranscriptTurn(transcriptState, details);
     }
 
-    renderWidget(ctx);
+    syncUi(ctx);
   }
 
   async function runBtw(
@@ -363,78 +1670,59 @@ export default function (pi: ExtensionAPI) {
     saveRequested: boolean,
     mode: BtwThreadMode,
   ): Promise<void> {
+    lastUiContext = ctx;
     const model = ctx.model;
     if (!model) {
+      setOverlayStatus("No active model selected.", ctx);
       notify(ctx, "No active model selected.", "error");
       return;
     }
 
     const apiKey = await ctx.modelRegistry.getApiKey(model);
     if (!apiKey) {
-      notify(ctx, `No credentials available for ${model.provider}/${model.id}.`, "error");
+      const message = `No credentials available for ${model.provider}/${model.id}.`;
+      setOverlayStatus(message, ctx);
+      notify(ctx, message, "error");
+      await ensureOverlay(ctx);
       return;
     }
 
+    const sessionRuntime = await ensureBtwSession(ctx, mode);
+    if (!sessionRuntime) {
+      setOverlayStatus("No active model selected.", ctx);
+      notify(ctx, "No active model selected.", "error");
+      return;
+    }
+
+    const session = sessionRuntime.session;
     const wasBusy = !ctx.isIdle();
     pendingMode = mode;
     const thinkingLevel = pi.getThinkingLevel() as SessionThinkingLevel;
-    const slot: BtwSlot = {
-      question,
-      modelLabel: `${model.provider}/${model.id}`,
-      thinking: "",
-      answer: "",
-      done: false,
-      controller: new AbortController(),
-    };
 
-    const threadSnapshot = pendingThread.slice();
-    slots.push(slot);
-    renderWidget(ctx);
+    setOverlayStatus("⏳ streaming...", ctx);
+    await ensureOverlay(ctx);
 
     try {
-      const stream = streamSimple(model, buildBtwContext(ctx, question, threadSnapshot, mode), {
-        apiKey,
-        reasoning: toReasoning(thinkingLevel),
-        signal: slot.controller.signal,
-      });
-
-      let response: AssistantMessage | null = null;
-
-      for await (const event of stream) {
-        if (event.type === "thinking_delta") {
-          slot.thinking += event.delta;
-          renderWidget(ctx);
-        } else if (event.type === "text_delta") {
-          slot.answer += event.delta;
-          renderWidget(ctx);
-        } else if (event.type === "done") {
-          response = event.message;
-        } else if (event.type === "error") {
-          response = event.error;
-        }
-      }
+      await session.prompt(question, { source: "extension" });
 
+      const response = getLastAssistantMessage(session);
       if (!response) {
         throw new Error("BTW request finished without a response.");
       }
       if (response.stopReason === "aborted") {
-        const slotIndex = slots.indexOf(slot);
-        if (slotIndex >= 0) {
-          slots.splice(slotIndex, 1);
-          renderWidget(ctx);
-        }
+        removeTranscriptTurn(transcriptState, transcriptState.lastTurnId ?? transcriptState.currentTurnId);
+        setOverlayStatus("Request aborted.", ctx);
         return;
       }
       if (response.stopReason === "error") {
         throw new Error(response.errorMessage || "BTW request failed.");
       }
 
+      const completedTurnId = transcriptState.lastTurnId ?? transcriptState.currentTurnId;
+      const streamedThinking =
+        completedTurnId !== null ? findLatestTranscriptEntry(transcriptState, completedTurnId, "thinking")?.text : "";
       const answer = extractAnswer(response);
-      const thinking = extractThinking(response) || slot.thinking;
-      slot.thinking = thinking;
-      slot.answer = answer;
-      slot.done = true;
-      renderWidget(ctx);
+      const thinking = extractThinking(response) || streamedThinking || "";
 
       const details: BtwDetails = {
         question,
@@ -453,27 +1741,43 @@ export default function (pi: ExtensionAPI) {
       const saveState = saveVisibleBtwNote(pi, details, saveRequested, wasBusy);
       if (saveState === "saved") {
         notify(ctx, "Saved BTW note to the session.", "info");
+        setOverlayStatus("Saved BTW note to the session.", ctx);
       } else if (saveState === "queued") {
         notify(ctx, "BTW note queued to save after the current turn finishes.", "info");
+        setOverlayStatus("BTW note queued to save after the current turn finishes.", ctx);
+      } else {
+        setOverlayStatus("Ready for a follow-up. Hidden BTW thread updated.", ctx);
       }
     } catch (error) {
-      if (slot.controller.signal.aborted) {
-        const slotIndex = slots.indexOf(slot);
-        if (slotIndex >= 0) {
-          slots.splice(slotIndex, 1);
-          renderWidget(ctx);
-        }
-        return;
-      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      setTranscriptFailure(transcriptState, errorMessage);
+      setOverlayStatus("Request failed. Thread preserved for retry or follow-up.", ctx);
+      notify(ctx, errorMessage, "error");
+      await disposeBtwSession();
+    } finally {
+      syncUi(ctx);
+    }
+  }
 
-      slot.answer = `❌ ${error instanceof Error ? error.message : String(error)}`;
-      slot.done = true;
-      renderWidget(ctx);
-      notify(ctx, error instanceof Error ? error.message : String(error), "error");
+  function getPendingThreadForHandoff(): BtwHandoffExchange[] {
+    return pendingThread.map((entry) => ({ user: entry.question, assistant: entry.answer }));
+  }
+
+  async function getBtwHandoffThread(
+    ctx: ExtensionCommandContext,
+  ): Promise<{ sessionRuntime: BtwSessionRuntime | null; thread: BtwHandoffExchange[] }> {
+    const sessionRuntime = activeBtwSession ?? (await ensureBtwSession(ctx, pendingMode));
+    const thread = sessionRuntime ? extractBtwHandoffThread(sessionRuntime) : [];
+    const resolvedThread = thread.length > 0 ? thread : getPendingThreadForHandoff();
+
+    if (resolvedThread.length === 0) {
+      throw new Error("No BTW thread available for handoff.");
     }
+
+    return { sessionRuntime, thread: resolvedThread };
   }
 
-  async function summarizeThread(ctx: ExtensionCommandContext, thread: BtwDetails[]): Promise<string> {
+  async function summarizeThread(ctx: ExtensionCommandContext, thread: BtwHandoffExchange[]): Promise<string> {
     const model = ctx.model;
     if (!model) {
       throw new Error("No active model selected.");
@@ -484,32 +1788,38 @@ export default function (pi: ExtensionAPI) {
       throw new Error(`No credentials available for ${model.provider}/${model.id}.`);
     }
 
-    const response = await completeSimple(
+    const { session } = await createAgentSession({
+      sessionManager: SessionManager.inMemory(),
       model,
-      {
-        systemPrompt: "Summarize the side conversation concisely. Preserve key decisions, plans, insights, risks, and action items. Output only the summary.",
-        messages: [
-          {
-            role: "user",
-            content: [{ type: "text", text: formatThread(thread) }],
-            timestamp: Date.now(),
-          },
-        ],
-      },
-      {
-        apiKey,
-        reasoning: "low",
-      },
-    );
+      modelRegistry: ctx.modelRegistry as AgentSession["modelRegistry"],
+      thinkingLevel: "off",
+      tools: [],
+      resourceLoader: createBtwResourceLoader(ctx, [BTW_SUMMARIZE_SYSTEM_PROMPT]),
+    });
 
-    if (response.stopReason === "error") {
-      throw new Error(response.errorMessage || "Failed to summarize BTW thread.");
-    }
-    if (response.stopReason === "aborted") {
-      throw new Error("BTW summarize aborted.");
-    }
+    try {
+      await session.prompt(formatThread(thread), { source: "extension" });
+
+      const response = getLastAssistantMessage(session);
+      if (!response) {
+        throw new Error("BTW summarize finished without a response.");
+      }
+      if (response.stopReason === "error") {
+        throw new Error(response.errorMessage || "Failed to summarize BTW thread.");
+      }
+      if (response.stopReason === "aborted") {
+        throw new Error("BTW summarize aborted.");
+      }
 
-    return extractAnswer(response);
+      return extractAnswer(response);
+    } finally {
+      try {
+        await session.abort();
+      } catch {
+        // Ignore abort errors during summarize session shutdown.
+      }
+      session.dispose();
+    }
   }
 
   function sendThreadToMain(ctx: ExtensionCommandContext, content: string): void {
@@ -552,123 +1862,70 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    restoreThread(ctx);
+    await restoreThread(ctx);
   });
 
   pi.on("session_switch", async (_event, ctx) => {
-    restoreThread(ctx);
+    await restoreThread(ctx);
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    restoreThread(ctx);
+    await restoreThread(ctx);
   });
 
   pi.on("session_shutdown", async () => {
-    abortActiveSlots();
+    await disposeBtwSession();
+    dismissOverlay();
   });
 
+  for (const shortcut of BTW_FOCUS_SHORTCUTS) {
+    pi.registerShortcut(shortcut, {
+      description: "Toggle BTW overlay focus while leaving it open.",
+      handler: async (_args, _ctx) => {
+        toggleOverlayFocus();
+      },
+    });
+  }
+
   pi.registerCommand("btw", {
-    description: "Continue a side conversation in a widget above the editor. Add --save to also persist a visible note.",
+    description: "Continue a side conversation in a focused BTW modal. Add --save to also persist a visible note.",
     handler: async (args, ctx) => {
-      const { question, save } = parseBtwArgs(args);
-      if (!question) {
-        notify(ctx, "Usage: /btw [--save] <question>", "warning");
-        return;
-      }
-
-      if (pendingMode !== "contextual") {
-        resetThread(ctx, true, "contextual");
-      }
-
-      await runBtw(ctx, question, save, "contextual");
+      await dispatchBtwCommand("btw", args, ctx);
     },
   });
 
   pi.registerCommand("btw:tangent", {
-    description: "Start or continue a contextless BTW tangent that does not inherit the main session context.",
+    description: "Start or continue a contextless BTW tangent in the focused BTW modal.",
     handler: async (args, ctx) => {
-      const { question, save } = parseBtwArgs(args);
-      if (!question) {
-        notify(ctx, "Usage: /btw:tangent [--save] <question>", "warning");
-        return;
-      }
-
-      if (pendingMode !== "tangent") {
-        resetThread(ctx, true, "tangent");
-      }
-
-      await runBtw(ctx, question, save, "tangent");
+      await dispatchBtwCommand("btw:tangent", args, ctx);
     },
   });
 
   pi.registerCommand("btw:new", {
     description: "Start a fresh BTW thread with main-session context. Optionally ask the first question immediately.",
     handler: async (args, ctx) => {
-      resetThread(ctx, true, "contextual");
-      const { question, save } = parseBtwArgs(args);
-      if (question) {
-        await runBtw(ctx, question, save, "contextual");
-      } else {
-        notify(ctx, "Started a fresh BTW thread.", "info");
-      }
+      await dispatchBtwCommand("btw:new", args, ctx);
     },
   });
 
   pi.registerCommand("btw:clear", {
-    description: "Dismiss the BTW widget and clear the current thread.",
-    handler: async (_args, ctx) => {
-      resetThread(ctx);
-      notify(ctx, "Cleared BTW thread.", "info");
+    description: "Dismiss the BTW modal/widget and clear the current thread.",
+    handler: async (args, ctx) => {
+      await dispatchBtwCommand("btw:clear", args, ctx);
     },
   });
 
   pi.registerCommand("btw:inject", {
     description: "Inject the full BTW thread into the main agent as a user message.",
     handler: async (args, ctx) => {
-      if (pendingThread.length === 0) {
-        notify(ctx, "No BTW thread to inject.", "warning");
-        return;
-      }
-
-      const instructions = args.trim();
-      const content = instructions
-        ? `Here is a side conversation I had. ${instructions}\n\n${formatThread(pendingThread)}`
-        : `Here is a side conversation I had for additional context:\n\n${formatThread(pendingThread)}`;
-
-      sendThreadToMain(ctx, content);
-      const count = pendingThread.length;
-      resetThread(ctx);
-      notify(ctx, `Injected BTW thread (${count} exchange${count === 1 ? "" : "s"}).`, "info");
+      await dispatchBtwCommand("btw:inject", args, ctx);
     },
   });
 
   pi.registerCommand("btw:summarize", {
     description: "Summarize the BTW thread, then inject the summary into the main agent.",
     handler: async (args, ctx) => {
-      if (pendingThread.length === 0) {
-        notify(ctx, "No BTW thread to summarize.", "warning");
-        return;
-      }
-
-      widgetStatus = "⏳ summarizing...";
-      renderWidget(ctx);
-
-      try {
-        const summary = await summarizeThread(ctx, pendingThread);
-        const instructions = args.trim();
-        const content = instructions
-          ? `Here is a summary of a side conversation I had. ${instructions}\n\n${summary}`
-          : `Here is a summary of a side conversation I had:\n\n${summary}`;
-
-        sendThreadToMain(ctx, content);
-        const count = pendingThread.length;
-        resetThread(ctx);
-        notify(ctx, `Injected BTW summary (${count} exchange${count === 1 ? "" : "s"}).`, "info");
-      } catch (error) {
-        widgetStatus = null;
-        renderWidget(ctx);
-        notify(ctx, error instanceof Error ? error.message : String(error), "error");
-      }
+      await dispatchBtwCommand("btw:summarize", args, ctx);
     },
   });
 }