agent-sh 0.14.9 → 0.14.11

package/examples/extensions/ashi/src/frontend.ts

@@ -1,42 +1,29 @@
-import {
-  TUI,
-  ProcessTerminal,
-  Container,
-  Editor,
-  Image,
-  Loader,
-  SelectList,
-  Spacer,
-  Text,
-  type Component,
-  type SelectItem,
-  getImageDimensions,
-  matchesKey,
-  isKeyRelease,
-  isKeyRepeat,
-} from "@earendil-works/pi-tui";
 import type { ExtensionContext } from "agent-sh/types";
-import { editorTheme, selectListTheme, theme } from "./theme.js";
-import {
-  AssistantMessage,
-  ErrorLine,
-  InfoLine,
-  ThinkingBlock,
-  ToolGroup,
-} from "./components.js";
-import type { ToolCallView, ToolResultView } from "./hooks.js";
-import { createToolHookResolver } from "./hooks.js";
+import { theme } from "./theme.js";
+import type {
+  KeyEvent,
+  KeyHandler,
+  LoaderView,
+  RenderNode,
+  Renderer,
+  SelectItem,
+  SelectView,
+  ToolCallView,
+  ToolResultView,
+} from "./renderer.js";
+import { ErrorLine, InfoLine } from "./chat/lines.js";
+import { AssistantMessage } from "./chat/assistant.js";
+import { ThinkingBlock } from "./chat/thinking.js";
+import { UserMessage } from "./chat/user-message.js";
+import { ToolGroup } from "./chat/tool-group.js";
+import { createToolHookResolver, type RenderState } from "./hooks.js";
 import { loadGroupMaxVisible } from "./display-config.js";
 import { classifySubmit, deriveChangeHandlerResult } from "./shell-mode.js";
 import { UserShellIntents } from "./user-shell-intents.js";
-
-const GROUPABLE_KINDS = new Set(["read", "search"]);
-const TOOL_KIND: Record<string, string> = {
-  read_file: "read", ls: "read",
-  grep: "search", glob: "search",
-};
 import { BusAutocompleteProvider } from "./autocomplete.js";
+import { createAutocompleteController } from "./autocomplete-controller.js";
 import { StatusFooter } from "./status-footer.js";
+import { applyOutputMode } from "./terminal-mode.js";
 import type { MultiSessionStore } from "./multi-session-store.js";
 import { stripContextWrappers, type SessionEntry } from "agent-sh/session-store";
 import { formatSessionRow } from "./session-commands.js";
@@ -44,16 +31,34 @@ import { resumeSession } from "./session-commands.js";
 import { applyBranchMessages } from "./commands.js";
 import type { Capture } from "./capture.js";
 import { execSync } from "node:child_process";
+import { readClipboardImage } from "./clipboard-image.js";
 import { renderDiff, detectLanguage, highlightLine } from "agent-sh/utils/diff-renderer.js";
 import { renderBoxFrame } from "agent-sh/utils/box-frame.js";
 
+const GROUPABLE_KINDS = new Set(["read", "search"]);
+const TOOL_KIND: Record<string, string> = {
+  read_file: "read", ls: "read",
+  grep: "search", glob: "search",
+};
+
 interface DiffStats { added: number; removed: number; isNewFile: boolean; isIdentical: boolean }
 
 function buildDiffRenderer(
   diff: DiffStats & Parameters<typeof renderDiff>[0],
   filePath: string,
+  boxed = true,
 ): (width: number) => string[] {
   return (width) => {
+    if (!boxed) {
+      // Drop renderDiff's header (lines[0]); file path is already on the call line.
+      const contentW = Math.max(20, width);
+      const inner = diff.isNewFile
+        ? renderNewFilePreview(diff, 30, filePath, false)
+        : renderDiff(diff, {
+            width: contentW, filePath, trueColor: true, maxLines: Number.MAX_SAFE_INTEGER, mode: "unified", gutterLine: false,
+          }).slice(1);
+      return trimBlankEdges(inner);
+    }
     const boxW = Math.max(40, width);
     const contentW = Math.max(20, boxW - 4);
     const inner = diff.isNewFile
@@ -72,10 +77,19 @@ function buildDiffRenderer(
   };
 }
 
+function trimBlankEdges(lines: string[]): string[] {
+  const blank = (s: string): boolean => s.replace(/\x1b\[[0-9;]*m/g, "").trim() === "";
+  let a = 0, b = lines.length;
+  while (a < b && blank(lines[a])) a++;
+  while (b > a && blank(lines[b - 1])) b--;
+  return lines.slice(a, b);
+}
+
 function renderNewFilePreview(
   diff: { hunks?: { lines: { type: string; text: string }[] }[] },
   maxLines: number,
   filePath: string,
+  gutterLine = true,
 ): string[] {
   const lines = diff.hunks?.[0]?.lines.filter((l) => l.type === "added") ?? [];
   const shown = lines.slice(0, maxLines);
@@ -84,7 +98,8 @@ function renderNewFilePreview(
   const lang = detectLanguage(filePath);
   const body = shown.map((l, i) => {
     const no = String(i + 1).padStart(noW);
-    return `${theme.fg("muted", `${no} │`)} ${highlightLine(l.text, lang)}`;
+    const code = highlightLine(l.text, lang);
+    return gutterLine ? `${theme.fg("muted", `${no} │`)} ${code}` : `\x1b[2m${no}\x1b[22m  ${code}`;
   });
   if (overflow > 0) body.push(theme.fg("muted", `… ${overflow} more lines`));
   return ["", ...body, ""];
@@ -128,12 +143,11 @@ function detailFromArgs(argsJson: string | undefined): string {
       const compact = args.source.replace(/\s+/g, " ").trim();
       return compact.length > 80 ? compact.slice(0, 77) + "…" : compact;
     }
-  } catch { /* fall through */ }
+  } catch { /* */ }
   return "";
 }
 
-/** resultDisplay isn't persisted, so /resume rebuilds the "16 entries" / "117
- *  lines" hints from saved tool output. */
+/** resultDisplay isn't persisted; /resume rebuilds these hints from saved tool output. */
 function inferSummary(toolName: string, content: unknown): string | undefined {
   if (typeof content !== "string" || content.length === 0) return undefined;
   const lines = content.split("\n").filter((l) => l.length > 0);
@@ -164,7 +178,6 @@ function relativize(fp: string): string {
 }
 
 export interface AshiHandle {
-  tui: TUI;
   stop: () => void;
   openTreePicker: () => Promise<void>;
   openSessionPicker: () => Promise<void>;
@@ -175,37 +188,35 @@ export function mountAshi(
   ctx: ExtensionContext,
   getStore: () => MultiSessionStore,
   capture: Capture,
+  renderer: Renderer,
 ): AshiHandle {
   const { bus } = ctx;
-  const terminal = new ProcessTerminal();
-  const tui = new TUI(terminal);
+  const app = renderer.mount();
+  const input = app.input;
 
-  const chat = new Container();
-  const footerSlot = new Container();
-  const queueSlot = new Container();
-  const editor = new Editor(tui, editorTheme(), { paddingX: 1 });
+  const statusFooter = new StatusFooter(app.status, renderer.measureWidth);
 
   let shellMode = false;
   let pendingPrivate = false;
-  const baseAutocomplete = new BusAutocompleteProvider(bus);
-  editor.setAutocompleteProvider({
-    getSuggestions: async (lines, line, col) =>
-      shellMode ? null : baseAutocomplete.getSuggestions(lines, line, col),
-    applyCompletion: baseAutocomplete.applyCompletion.bind(baseAutocomplete),
+  const autocomplete = createAutocompleteController({
+    app,
+    input,
+    provider: new BusAutocompleteProvider(bus),
+    suppressed: () => shellMode,
   });
 
-  const defaultBorderColor = editor.borderColor;
+  const defaultBorderColor = input.defaultBorderColor;
   const shellBorderColor = (t: string): string => theme.fg("bashMode", t);
   const privateBorderColor = (t: string): string => theme.fg("bashModePrivate", t);
   const refreshShellChrome = (): void => {
-    editor.borderColor = shellMode
+    input.setBorderColor(shellMode
       ? (pendingPrivate ? privateBorderColor : shellBorderColor)
-      : defaultBorderColor;
-    editor.invalidate();
+      : defaultBorderColor);
+    input.invalidate();
     statusFooter.update({
       shellMode: shellMode ? (pendingPrivate ? "private" : "on") : "off",
     });
-    tui.requestRender();
+    app.requestRender();
   };
   const setShellMode = (on: boolean): void => {
     if (shellMode === on) return;
@@ -219,41 +230,41 @@ export function mountAshi(
     refreshShellChrome();
   };
 
-  editor.onChange = (text) => {
+  input.onChange((text) => {
     const r = deriveChangeHandlerResult(shellMode, pendingPrivate, text);
-    // Order matters: setText fires onChange synchronously, and the recursive
-    // call must see the new mode/private values or it re-runs the entry
-    // transition and clobbers the just-set state.
+    // setText fires onChange synchronously; set mode/private before setText or the recursive call clobbers it.
     if (r.mode !== shellMode) setShellMode(r.mode);
     setPendingPrivate(r.pendingPrivate);
-    if (r.replaceText !== undefined) editor.setText(r.replaceText);
-  };
+    if (r.replaceText !== undefined) input.setText(r.replaceText);
+    autocomplete.refresh();
+  });
 
-  editor.onSubmit = (text) => {
+  input.onSubmit((text) => {
     const action = classifySubmit(text, shellMode, pendingPrivate);
     if (action.kind === "noop") return;
-    editor.setText("");
+    input.setText("");
     switch (action.kind) {
       case "shell":
         submitShell(action.line, { private: action.private });
-        setPendingPrivate(false);
         return;
       case "command":
         bus.emit("command:execute", { name: action.name, args: action.args });
         return;
-      case "agent":
+      case "agent": {
+        const imgs = pendingImages.filter((p) => action.query.includes(`[Image #${p.id}]`));
+        pendingImages = [];
         if (processing) {
-          queuedQueries.push(action.query);
+          queuedQueries.push({ query: action.query, images: imgs });
           renderQueueSlot();
-          tui.requestRender();
+          app.requestRender();
           return;
         }
-        bus.emit("agent:submit", { query: action.query });
+        bus.emit("agent:submit", { query: action.query, images: imgs.length ? toImageContent(imgs) : undefined });
         return;
+      }
     }
-  };
+  });
 
-  const statusFooter = new StatusFooter();
   const cwd = ctx.call("cwd") as string;
   statusFooter.update({ cwd, branch: currentGitBranch(cwd) });
   let compactions = 0;
@@ -271,12 +282,21 @@ export function mountAshi(
     statusFooter.update({ thinking: supported ? level : undefined });
   };
 
-  tui.addChild(chat);
-  tui.addChild(footerSlot);
-  tui.addChild(queueSlot);
-  tui.addChild(editor);
-  tui.addChild(statusFooter);
-  tui.setFocus(editor);
+  type ChatEntry =
+    | { t: "group"; group: ToolGroup }
+    | { t: "thinking"; ctrl: ThinkingBlock }
+    | { t: "assistant"; ctrl: AssistantMessage }
+    | { t: "pair"; result: ToolResultView }
+    | { t: "plain" };
+  const chatEntries: ChatEntry[] = [];
+  const appendEntry = (node: RenderNode, entry: ChatEntry): void => {
+    app.scrollback.addChild(node);
+    chatEntries.push(entry);
+  };
+  const clearChat = (): void => {
+    app.scrollback.clear();
+    chatEntries.length = 0;
+  };
 
   interface ToolPair { call: ToolCallView; result: ToolResultView; startedAt: number }
   type LiveToolEntry = { kind: "pair"; pair: ToolPair } | { kind: "group"; group: ToolGroup };
@@ -286,35 +306,46 @@ export function mountAshi(
   const activeTools = new Map<string, LiveToolEntry>();
   const groupMaxVisible = loadGroupMaxVisible();
 
+  let openGroup: ToolGroup | null = null;
+  const sealOpenGroup = (): void => {
+    if (openGroup) { openGroup.seal(); openGroup = null; }
+  };
+
   /** Visible thinking acts as a hard separator; hidden thinking is transparent. */
   const findMergeableGroup = (kind: string): ToolGroup | null => {
-    for (let i = chat.children.length - 1; i >= 0; i--) {
-      const c = chat.children[i]!;
-      if (c instanceof ToolGroup) return c.kind === kind ? c : null;
-      if (c instanceof ThinkingBlock && hideThinking) continue;
-      if (c instanceof AssistantMessage && !c.hasContent()) continue;
+    for (let i = chatEntries.length - 1; i >= 0; i--) {
+      const e = chatEntries[i]!;
+      if (e.t === "group") return e.group.kind === kind ? e.group : null;
+      if (e.t === "thinking" && hideThinking) continue;
+      if (e.t === "assistant" && !e.ctrl.hasContent()) continue;
       return null;
     }
     return null;
   };
-  let loader: Loader | null = null;
+  let loader: LoaderView | null = null;
+  let loaderGap: RenderNode | null = null;
   let processing = false;
-  const queuedQueries: string[] = [];
+  type PendingImage = { id: number; data: string; mimeType: string };
+  let pendingImages: PendingImage[] = [];
+  let imageCounter = 0;
+  const toImageContent = (imgs: PendingImage[]) =>
+    imgs.map(({ data, mimeType }) => ({ type: "image" as const, data, mimeType }));
+  const queuedQueries: { query: string; images: PendingImage[] }[] = [];
   const queuedShellLines: { line: string; private: boolean }[] = [];
   const pendingUserShell = new UserShellIntents();
 
   const renderQueueSlot = (): void => {
-    queueSlot.clear();
+    app.queueSlot.clear();
     for (const item of queuedShellLines) {
       const oneLine = item.line.replace(/\s+/g, " ");
       const preview = oneLine.length > 80 ? oneLine.slice(0, 77) + "…" : oneLine;
       const tag = item.private ? "shell·private" : "shell";
-      queueSlot.addChild(new InfoLine(`↳ ${tag}: ${preview}`));
+      app.queueSlot.addChild(new InfoLine(renderer, `↳ ${tag}: ${preview}`).node);
     }
     for (const q of queuedQueries) {
-      const oneLine = q.replace(/\s+/g, " ");
+      const oneLine = q.query.replace(/\s+/g, " ");
       const preview = oneLine.length > 80 ? oneLine.slice(0, 77) + "…" : oneLine;
-      queueSlot.addChild(new InfoLine(`↳ queued: ${preview}`));
+      app.queueSlot.addChild(new InfoLine(renderer, `↳ queued: ${preview}`).node);
     }
   };
 
@@ -322,7 +353,7 @@ export function mountAshi(
     if (processing) {
       queuedShellLines.push({ line, private: !!opts?.private });
       renderQueueSlot();
-      tui.requestRender();
+      app.requestRender();
       return;
     }
     pendingUserShell.push({ private: !!opts?.private });
@@ -331,27 +362,28 @@ export function mountAshi(
   };
   let hideThinking = true;
 
-  const renderState = (): { state: Record<string, unknown>; invalidate: () => void } => ({
+  const renderState = (): RenderState => ({
     state: {},
-    invalidate: () => tui.requestRender(),
+    invalidate: () => app.requestRender(),
+    nodes: renderer,
   });
 
-  const tools = createToolHookResolver(ctx);
+  const tools = createToolHookResolver(ctx, renderer);
 
-  const renderUserMessage = (text: string): Component =>
-    ctx.call("ashi:render-user-message", { text, ...renderState() }) as Component;
+  const renderUserMessage = (text: string): RenderNode =>
+    (ctx.call("ashi:render-user-message", { text, ...renderState() }) as UserMessage).node;
 
   const renderAssistantLive = (): AssistantMessage =>
     ctx.call("ashi:render-assistant", { text: "", ...renderState() }) as AssistantMessage;
 
-  const renderAssistantFinal = (text: string): Component =>
-    ctx.call("ashi:render-assistant", { text, ...renderState() }) as Component;
+  const renderAssistantFinal = (text: string): AssistantMessage =>
+    ctx.call("ashi:render-assistant", { text, ...renderState() }) as AssistantMessage;
 
   const renderThinkingLive = (): ThinkingBlock =>
     ctx.call("ashi:render-thinking", { text: "", hidden: hideThinking, ...renderState() }) as ThinkingBlock;
 
-  const renderThinkingFinal = (text: string): Component =>
-    ctx.call("ashi:render-thinking", { text, hidden: hideThinking, ...renderState() }) as Component;
+  const renderThinkingFinal = (text: string): ThinkingBlock =>
+    ctx.call("ashi:render-thinking", { text, hidden: hideThinking, ...renderState() }) as ThinkingBlock;
 
   const renderToolPair = (args: {
     toolCallId: string; name: string; title: string;
@@ -370,7 +402,7 @@ export function mountAshi(
   const ensureAssistant = (): AssistantMessage => {
     if (!activeAssistant) {
       activeAssistant = renderAssistantLive();
-      chat.addChild(activeAssistant);
+      appendEntry(activeAssistant.node, { t: "assistant", ctrl: activeAssistant });
     }
     return activeAssistant;
   };
@@ -385,20 +417,24 @@ export function mountAshi(
   const ensureThinking = (): ThinkingBlock => {
     if (!activeThinking) {
       activeThinking = renderThinkingLive();
-      chat.addChild(activeThinking);
+      appendEntry(activeThinking.node, { t: "thinking", ctrl: activeThinking });
     }
     return activeThinking;
   };
 
   const startLoader = (): void => {
     if (loader) return;
-    loader = new Loader(tui, fgAccent, fgMuted, "thinking…");
-    footerSlot.addChild(loader);
+    loaderGap = renderer.spacer(1);
+    app.footerSlot.addChild(loaderGap);
+    loader = app.createLoader("thinking…", fgAccent, fgMuted);
+    app.footerSlot.addChild(loader.node);
   };
   const stopLoader = (): void => {
     if (!loader) return;
     loader.stop();
-    footerSlot.removeChild(loader);
+    app.footerSlot.removeChild(loader.node);
+    if (loaderGap) app.footerSlot.removeChild(loaderGap);
+    loaderGap = null;
     loader = null;
   };
 
@@ -409,7 +445,10 @@ export function mountAshi(
   const replayEntry = (entry: SessionEntry, toolMap: Map<string, ReplayEntry>): void => {
     if (entry.type === "session") return;
     if (entry.type === "compaction") {
-      chat.addChild(new InfoLine(`▼ compacted (firstKept=${entry.firstKeptId.slice(0, 6)}, ${entry.tokensBefore} tokens)`));
+      appendEntry(
+        new InfoLine(renderer, `▼ compacted (firstKept=${entry.firstKeptId.slice(0, 6)}, ${entry.tokensBefore} tokens)`).node,
+        { t: "plain" },
+      );
       return;
     }
     if (entry.type === "shell-exchange") {
@@ -418,27 +457,35 @@ export function mountAshi(
         toolCallId: `user-shell-replay-${entry.id}`, name, title: name,
         kind: "bash", displayDetail: entry.command, rawInput: { command: entry.command },
       });
-      chat.addChild(pair.call);
-      chat.addChild(pair.result);
+      appendEntry(pair.call.node, { t: "plain" });
+      appendEntry(pair.result.node, { t: "pair", result: pair.result });
       if (entry.output) pair.result.appendChunk(entry.output);
       pair.result.finalize({ exitCode: entry.exitCode });
       pair.call.setStatus({ exitCode: entry.exitCode, elapsedMs: 0 });
-      chat.addChild(new Spacer(1));
       return;
     }
     const m = entry.message;
     if (m.role === "user") {
-      const raw = typeof m.content === "string" ? m.content : "";
+      const raw = typeof m.content === "string"
+        ? m.content
+        : Array.isArray(m.content)
+          ? (m.content as Array<{ type?: string; text?: string }>)
+              .filter((p) => p.type === "text")
+              .map((p) => p.text ?? "")
+              .join("")
+          : "";
       if (raw.startsWith("[Compacted conversation summary]")) return;
-      chat.addChild(renderUserMessage(stripContextWrappers(raw)));
+      appendEntry(renderUserMessage(stripContextWrappers(raw)), { t: "plain" });
     } else if (m.role === "assistant") {
       const reasoning = readReasoning(m);
       if (reasoning) {
-        chat.addChild(renderThinkingFinal(reasoning));
+        const tb = renderThinkingFinal(reasoning);
+        appendEntry(tb.node, { t: "thinking", ctrl: tb });
       }
       const text = typeof m.content === "string" ? m.content : "";
       if (text) {
-        chat.addChild(renderAssistantFinal(text));
+        const am = renderAssistantFinal(text);
+        appendEntry(am.node, { t: "assistant", ctrl: am });
       }
       if (m.tool_calls) {
         for (const tc of m.tool_calls) {
@@ -446,10 +493,10 @@ export function mountAshi(
           const id = tc.id ?? "";
           const name = tc.function.name ?? "tool";
           const kind = TOOL_KIND[name];
-          if (kind && GROUPABLE_KINDS.has(kind)) {
+          if (kind && GROUPABLE_KINDS.has(kind) && renderer.mountToolGroup) {
             const mergeable = findMergeableGroup(kind);
             const group = mergeable
-              ?? (() => { const g = new ToolGroup(kind, groupMaxVisible); chat.addChild(g); return g; })();
+              ?? (() => { const g = new ToolGroup(renderer, kind, groupMaxVisible); appendEntry(g.node, { t: "group", group: g }); return g; })();
             group.addCall(id, name, detailFromArgs(tc.function.arguments));
             if (id) toolMap.set(id, { kind: "group", group, name });
             continue;
@@ -459,8 +506,8 @@ export function mountAshi(
             displayDetail: detailFromArgs(tc.function.arguments),
             rawInput: tc.function.arguments,
           });
-          chat.addChild(pair.call);
-          chat.addChild(pair.result);
+          appendEntry(pair.call.node, { t: "plain" });
+          appendEntry(pair.result.node, { t: "pair", result: pair.result });
           if (id) toolMap.set(id, { kind: "pair", pair, name });
         }
       }
@@ -469,7 +516,7 @@ export function mountAshi(
       const text = typeof m.content === "string" ? m.content : "";
       const found = id ? toolMap.get(id) : undefined;
       if (!found) {
-        chat.addChild(new InfoLine(`tool result (no matching call): ${text.slice(0, 80)}`));
+        appendEntry(new InfoLine(renderer, `tool result (no matching call): ${text.slice(0, 80)}`).node, { t: "plain" });
         return;
       }
       const summary = inferSummary(found.name, text);
@@ -480,7 +527,7 @@ export function mountAshi(
         if (meta?.diff && typeof meta.filePath === "string") {
           const diff = meta.diff as DiffStats & Parameters<typeof renderDiff>[0];
           if (!diff.isIdentical) {
-            found.pair.result.setDiffRenderer(buildDiffRenderer(diff, meta.filePath));
+            found.pair.result.setDiffRenderer(buildDiffRenderer(diff, meta.filePath, renderer.capabilities.diffFrame !== false));
           }
         }
         found.pair.result.finalize({ exitCode: 0, summary });
@@ -494,66 +541,78 @@ export function mountAshi(
     activeAssistant = null;
     activeThinking = null;
     activeTools.clear();
-    chat.clear();
+    openGroup = null;
+    clearChat();
     const branch = getStore().current().getBranch();
     const toolMap = new Map<string, ReplayEntry>();
     for (const e of branch) replayEntry(e, toolMap);
-    chat.addChild(new Spacer(1));
-    tui.requestRender();
+    for (const entry of chatEntries) if (entry.t === "group") entry.group.seal();
+    app.commitScrollback?.();
+    app.requestRender();
   };
 
   bus.on("agent:query", ({ query }) => {
-    chat.addChild(renderUserMessage(query));
+    app.commitScrollback?.();
+    sealOpenGroup();
+    appendEntry(renderUserMessage(query), { t: "plain" });
     activeAssistant = null;
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("agent:processing-start", () => {
     processing = true;
     startLoader();
-    tui.requestRender();
+    app.requestRender();
   });
 
-  const imageComponentFromPng = (data: Buffer): Image | null => {
-    const base64 = data.toString("base64");
-    const dims = getImageDimensions(base64, "image/png");
-    if (!dims) return null;
-    return new Image(
-      base64, "image/png",
-      { fallbackColor: (t) => theme.fg("muted", t) },
-      { maxWidthCells: 60, maxHeightCells: 20 },
-      dims,
-    );
-  };
-
-  /** Drop the live assistant so subsequent text starts fresh markdown below the image. */
   const appendImage = (data: Buffer): void => {
-    const img = imageComponentFromPng(data);
+    const img = renderer.image(data);
     if (!img) return;
+    sealOpenGroup();
     if (activeAssistant) { activeAssistant.finalize(); activeAssistant = null; }
-    chat.addChild(img);
+    appendEntry(img, { t: "plain" });
   };
 
   /** tui-renderer normally owns this hook; ashi disables it and provides its own. */
   ctx.define("render:image", (data: Buffer) => {
     appendImage(data);
-    tui.requestRender();
+    app.requestRender();
+  });
+
+  // Only [Image #N] markers still in the text at submit are sent — deleting one drops its image.
+  const attachImage = (img: { data: string; mimeType: string }): void => {
+    const id = ++imageCounter;
+    pendingImages.push({ id, data: img.data, mimeType: img.mimeType });
+    input.replaceBeforeCursor(0, `[Image #${id}] `);
+    app.requestRender();
+  };
+  // Ctrl+V (wired below) and /paste capture a clipboard image; Cmd+V stays text paste.
+  const captureClipboardImage = (): void => {
+    void readClipboardImage().then((img) => {
+      if (img) attachImage(img);
+      else bus.emit("ui:info", { message: "No image found on the clipboard." });
+    });
+  };
+  ctx.registerCommand("paste", "Attach an image from the clipboard to your next message", async () => {
+    captureClipboardImage();
   });
 
   bus.on("agent:response-chunk", ({ blocks }) => {
+    sealOpenGroup();
     finalizeThinking();
     for (const b of blocks) {
       if (b.type === "text") ensureAssistant().appendText(b.text);
       else if (b.type === "code-block") ensureAssistant().appendCodeBlock(b.language, b.code);
       else if (b.type === "image") appendImage(b.data);
     }
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("agent:thinking-chunk", ({ text }) => {
+    if (!hideThinking) sealOpenGroup();
     if (activeAssistant) { activeAssistant.finalize(); activeAssistant = null; }
     ensureThinking().appendText(text);
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("agent:tool-started", (e) => {
@@ -570,31 +629,34 @@ export function mountAshi(
     );
 
     const kind = e.kind ?? "";
-    if (GROUPABLE_KINDS.has(kind)) {
+    if (GROUPABLE_KINDS.has(kind) && renderer.mountToolGroup) {
       const mergeable = findMergeableGroup(kind);
+      if (!mergeable) sealOpenGroup();
       const group = mergeable
-        ?? (() => { const g = new ToolGroup(kind, groupMaxVisible); chat.addChild(g); return g; })();
+        ?? (() => { const g = new ToolGroup(renderer, kind, groupMaxVisible); appendEntry(g.node, { t: "group", group: g }); return g; })();
       group.addCall(id, lookupName, detail);
+      openGroup = group;
       activeTools.set(id, { kind: "group", group });
-      tui.requestRender();
+      app.requestRender();
       return;
     }
 
+    sealOpenGroup();
     const pair = renderToolPair({
       toolCallId: id, name: lookupName, title, kind: e.kind,
       displayDetail: detail, rawInput: e.rawInput,
     });
     activeTools.set(id, { kind: "pair", pair });
-    chat.addChild(pair.call);
-    chat.addChild(pair.result);
-    tui.requestRender();
+    appendEntry(pair.call.node, { t: "plain" });
+    appendEntry(pair.result.node, { t: "pair", result: pair.result });
+    app.requestRender();
   });
 
   bus.on("agent:tool-output-chunk", ({ chunk }) => {
     for (const entry of [...activeTools.values()].reverse()) {
       if (entry.kind === "pair") {
         entry.pair.result.appendChunk(chunk);
-        tui.requestRender();
+        app.requestRender();
         return;
       }
     }
@@ -609,7 +671,7 @@ export function mountAshi(
     if (entry.kind === "group") {
       entry.group.recordCompletion(id, e.exitCode, summary);
       activeTools.delete(id);
-      tui.requestRender();
+      app.requestRender();
       return;
     }
     const pair = entry.pair;
@@ -617,17 +679,16 @@ export function mountAshi(
     if (body?.kind === "diff") {
       const diff = body.diff as DiffStats & Parameters<typeof renderDiff>[0];
       if (!diff.isIdentical) {
-        pair.result.setDiffRenderer(buildDiffRenderer(diff, body.filePath));
+        pair.result.setDiffRenderer(buildDiffRenderer(diff, body.filePath, renderer.capabilities.diffFrame !== false));
       }
     }
     pair.call.setStatus({ exitCode: e.exitCode, elapsedMs: Date.now() - pair.startedAt, summary });
     pair.result.finalize({ exitCode: e.exitCode, summary });
     activeTools.delete(id);
-    tui.requestRender();
+    app.requestRender();
   });
 
-  // agent:tool-* listeners already render agent-issued bash; the shell:* path
-  // is only for user-issued `!` commands.
+  // shell:* path is only for user-issued `!` commands; agent bash renders via agent:tool-*.
   let agentShellActive = false;
   let shellForegroundBusy = false;
   bus.on("shell:agent-exec-start", () => { agentShellActive = true; });
@@ -648,9 +709,9 @@ export function mountAshi(
       kind: "bash", displayDetail: command, rawInput: { command },
     });
     activeUserShell = { pair, command, isPrivate };
-    chat.addChild(pair.call);
-    chat.addChild(pair.result);
-    tui.requestRender();
+    appendEntry(pair.call.node, { t: "plain" });
+    appendEntry(pair.result.node, { t: "pair", result: pair.result });
+    app.requestRender();
   });
 
   bus.on("shell:command-done", ({ output, cwd, exitCode }) => {
@@ -661,8 +722,7 @@ export function mountAshi(
     pair.call.setStatus({ exitCode, elapsedMs: Date.now() - pair.startedAt });
     pair.result.finalize({ exitCode });
     activeUserShell = null;
-    chat.addChild(new Spacer(1));
-    tui.requestRender();
+    app.requestRender();
     void getStore().current().appendShellExchange({
       command, output: output ?? "", exitCode, cwd,
       ...(isPrivate ? { private: true } : {}),
@@ -673,12 +733,12 @@ export function mountAshi(
   bus.on("agent:processing-done", () => {
     processing = false;
     stopLoader();
+    sealOpenGroup();
     finalizeThinking();
     if (activeAssistant) activeAssistant.finalize();
-    chat.addChild(new Spacer(1));
     refreshFooterStats();
     refreshBranch();
-    // Shell queue drains first so its output lands in the next turn's <shell_events>.
+    // Drain shell queue before queries so its output lands in the next turn's <shell_events>.
     while (queuedShellLines.length > 0) {
       const item = queuedShellLines.shift()!;
       pendingUserShell.push({ private: item.private });
@@ -688,42 +748,44 @@ export function mountAshi(
     const next = queuedQueries.shift();
     if (next !== undefined) {
       renderQueueSlot();
-      bus.emit("agent:submit", { query: next });
+      bus.emit("agent:submit", { query: next.query, images: next.images.length ? toImageContent(next.images) : undefined });
     } else {
       renderQueueSlot();
     }
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("agent:usage", (u) => {
     if (u.prompt_tokens > 0) {
       statusFooter.update({ tokens: u.prompt_tokens });
-      tui.requestRender();
+      app.requestRender();
     }
   });
 
   bus.on("agent:cancelled", () => {
     processing = false;
     stopLoader();
-    chat.addChild(new InfoLine("cancelled"));
-    tui.requestRender();
+    sealOpenGroup();
+    appendEntry(new InfoLine(renderer, "cancelled").node, { t: "plain" });
+    app.requestRender();
   });
 
   bus.on("agent:error", ({ message }) => {
     processing = false;
     stopLoader();
-    chat.addChild(new ErrorLine(message));
-    tui.requestRender();
+    sealOpenGroup();
+    appendEntry(new ErrorLine(renderer, message).node, { t: "plain" });
+    app.requestRender();
   });
 
   bus.on("ui:info", ({ message }) => {
-    chat.addChild(new InfoLine(message));
-    tui.requestRender();
+    appendEntry(new InfoLine(renderer, message).node, { t: "plain" });
+    app.requestRender();
   });
 
   bus.on("ui:error", ({ message }) => {
-    chat.addChild(new ErrorLine(message));
-    tui.requestRender();
+    appendEntry(new ErrorLine(renderer, message).node, { t: "plain" });
+    app.requestRender();
   });
 
   bus.on("agent:info", (info) => {
@@ -733,25 +795,25 @@ export function mountAshi(
       contextWindow: info.contextWindow,
     });
     refreshThinking();
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("config:changed", () => {
     refreshThinking();
-    tui.requestRender();
+    app.requestRender();
   });
 
   bus.on("conversation:after-compact", () => {
     compactions++;
     statusFooter.update({ compactions });
     refreshFooterStats();
-    tui.requestRender();
+    app.requestRender();
   });
 
   refreshFooterStats();
 
   let pickerOpen = false;
-  let activeSessionPicker: SelectList | null = null;
+  let activeSessionPicker: SelectView | null = null;
   let activeSessionRepopulate: ((keepIndex?: number) => boolean) | null = null;
   let activeSessionClose: (() => void) | null = null;
 
@@ -806,8 +868,6 @@ export function mountAshi(
         const only = byId.get(kids[0]!);
         const isTip = !!only && !(only.type === "message" && only.message.role === "user");
         if (isTip) {
-          // Render the tip as a branch-child so it gets a `└` connector at
-          // a deeper indent, visually "the next node in this branch."
           walk(kids[0]!, [...lineage, " "], true);
         } else {
           walk(kids[0]!, lineage, false);
@@ -850,18 +910,18 @@ export function mountAshi(
       const label = r.id === activeLeaf ? "● current" : "leaf";
       return { value: `tip:${r.id}`, label: `${treePrefix}${label}` };
     });
-    const picker = new SelectList(items, 15, selectListTheme());
+    const picker = app.createSelectList(items, { visibleRows: 15 });
     const activeIdx = items.findIndex((it) => it.value === `tip:${activeLeaf}`);
     picker.setSelectedIndex(activeIdx >= 0 ? activeIdx : items.length - 1);
 
     const close = (): void => {
       pickerOpen = false;
-      footerSlot.removeChild(picker);
-      tui.setFocus(editor);
-      tui.requestRender();
+      app.footerSlot.removeChild(picker.node);
+      app.focusInput();
+      app.requestRender();
     };
 
-    picker.onSelect = async (item) => {
+    picker.onSelect(async (item) => {
       close();
       const [kind, id] = item.value.split(":") as ["msg" | "tip", string];
       if (kind === "tip") {
@@ -879,37 +939,37 @@ export function mountAshi(
       store.setActiveLeaf(targetLeaf);
       applyBranchMessages(ctx, getStore, capture);
       const raw = typeof entry.message.content === "string" ? entry.message.content : "";
-      editor.setText(stripContextWrappers(raw));
+      input.setText(stripContextWrappers(raw));
       bus.emit("ui:info", { message: `fork: rewound to ${targetLeaf.slice(0, 6)}` });
       await rebuildChat();
       refreshFooterStats();
-    };
-    picker.onCancel = close;
+    });
+    picker.onCancel(close);
 
     pickerOpen = true;
-    footerSlot.addChild(picker);
-    tui.setFocus(picker);
-    tui.requestRender();
+    app.footerSlot.addChild(picker.node);
+    app.setFocus(picker.node);
+    app.requestRender();
   };
 
   const openSessionPicker = async (): Promise<void> => {
     if (pickerOpen) return;
 
-    const hint = new InfoLine("↑↓ move · enter: resume · d: delete · esc: cancel");
+    const hint = new InfoLine(renderer, "↑↓ move · enter: resume · d: delete · esc: cancel");
 
     const close = (): void => {
-      if (activeSessionPicker) footerSlot.removeChild(activeSessionPicker);
-      footerSlot.removeChild(hint);
+      if (activeSessionPicker) app.footerSlot.removeChild(activeSessionPicker.node);
+      app.footerSlot.removeChild(hint.node);
       activeSessionPicker = null;
       activeSessionRepopulate = null;
       activeSessionClose = null;
       pickerOpen = false;
-      tui.setFocus(editor);
-      tui.requestRender();
+      app.focusInput();
+      app.requestRender();
     };
 
     const populate = (keepIndex?: number): boolean => {
-      if (activeSessionPicker) footerSlot.removeChild(activeSessionPicker);
+      if (activeSessionPicker) app.footerSlot.removeChild(activeSessionPicker.node);
       const currentId = getStore().current().id;
       const list = getStore().listSessions().filter((s) => s.id !== currentId);
       if (list.length === 0) {
@@ -920,69 +980,103 @@ export function mountAshi(
         value: s.id,
         label: formatSessionRow(s, false),
       }));
-      const picker = new SelectList(items, 15, selectListTheme());
+      const picker = app.createSelectList(items, { visibleRows: 15 });
       if (keepIndex !== undefined) {
         picker.setSelectedIndex(Math.min(keepIndex, items.length - 1));
       }
-      picker.onSelect = async (item) => {
+      picker.onSelect(async (item) => {
         const id = item.value;
         close();
         resumeSession(ctx, getStore, capture, id);
         bus.emit("ui:info", { message: `resumed session ${id}` });
         await rebuildChat();
         refreshFooterStats();
-      };
-      picker.onCancel = close;
+      });
+      picker.onCancel(close);
       activeSessionPicker = picker;
-      footerSlot.addChild(picker);
-      tui.setFocus(picker);
+      app.footerSlot.addChild(picker.node);
+      app.setFocus(picker.node);
       return true;
     };
 
-    footerSlot.addChild(hint);
+    app.footerSlot.addChild(hint.node);
     if (!populate()) {
-      footerSlot.removeChild(hint);
+      app.footerSlot.removeChild(hint.node);
       bus.emit("ui:info", { message: "no past sessions in this cwd" });
       return;
     }
     pickerOpen = true;
     activeSessionRepopulate = populate;
     activeSessionClose = close;
-    tui.requestRender();
+    app.requestRender();
   };
 
   const toggleThinking = (): void => {
     hideThinking = !hideThinking;
-    if (processing) {
-      // Mid-turn: only show/hide existing nodes. Group-merging respects the
-      // new flag for future calls; next idle rebuild reflows everything.
-      const walk = (node: Container): void => {
-        for (const child of node.children) {
-          if (child instanceof ThinkingBlock) child.setHidden(hideThinking);
-          else if (child instanceof Container) walk(child);
-        }
-      };
-      walk(chat);
-      tui.requestRender();
-      return;
+    // Reasoning isn't persisted; toggle live controllers instead of rebuilding.
+    for (const e of chatEntries) {
+      if (e.t === "thinking") e.ctrl.setHidden(hideThinking);
     }
-    void rebuildChat();
+    app.requestRender();
   };
 
-  tui.addInputListener((data) => {
-    if (isKeyRelease(data) || isKeyRepeat(data)) return;
-    if (matchesKey(data, "escape")) {
+  const jobControl = process.platform !== "win32";
+  let suspended = false;
+  let terminalYielded = false;
+  const resumeFromSuspend = (): void => {
+    if (!suspended) return;
+    suspended = false;
+    applyOutputMode(renderer.capabilities.rawOutput);
+    app.start();
+    app.requestRender(true);
+  };
+  const suspendToShell = (): void => {
+    if (suspended || terminalYielded) return;
+    suspended = true;
+    app.stop();
+    process.kill(process.pid, "SIGSTOP");
+  };
+  if (jobControl) process.on("SIGCONT", resumeFromSuspend);
+
+  ctx.define("ashi:terminal:yield", async (run: () => unknown | Promise<unknown>) => {
+    if (terminalYielded || suspended) return;
+    terminalYielded = true;
+    const wasRaw = process.stdin.isRaw;
+    app.stop();
+    applyOutputMode(true);
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    try {
+      return await run();
+    } finally {
+      process.stdin.setRawMode?.(wasRaw);
+      applyOutputMode(renderer.capabilities.rawOutput);
+      app.start();
+      app.requestRender(true);
+      terminalYielded = false;
+    }
+  });
+
+  ctx.define("ashi:on-key", (handler: KeyHandler) => app.onKey(handler));
+
+  app.onKey((key: KeyEvent) => {
+    if (key.isRelease() || key.isRepeat()) return;
+    if (key.matches("ctrl+v")) {
+      captureClipboardImage();
+      return { consume: true };
+    }
+    if (key.matches("escape")) {
       if (processing) {
         bus.emit("agent:cancel-request", {});
         return { consume: true };
       }
       if (shellForegroundBusy) {
-        // Real ^C byte; PTY translates it to SIGINT for the foreground process.
+        // Literal ^C byte; PTY translates to SIGINT for the foreground process.
         bus.emit("shell:pty-write", { data: "\x03" });
         return { consume: true };
       }
     }
-    if (activeSessionPicker && matchesKey(data, "d")) {
+    if (activeSessionPicker && key.matches("d")) {
       const selected = activeSessionPicker.getSelectedItem();
       if (selected) {
         const currentId = getStore().current().id;
@@ -996,37 +1090,41 @@ export function mountAshi(
           return { consume: true };
         }
         if (!activeSessionRepopulate?.(idx)) activeSessionClose?.();
-        tui.requestRender();
+        app.requestRender();
       }
       return { consume: true };
     }
-    if (matchesKey(data, "up") && queuedQueries.length > 0 && editor.getText().length === 0) {
+    if (key.matches("up") && queuedQueries.length > 0 && input.getText().length === 0) {
       const last = queuedQueries.pop()!;
       renderQueueSlot();
-      editor.setText(last);
-      tui.requestRender();
+      input.setText(last.query);
+      pendingImages = last.images;
+      app.requestRender();
       return { consume: true };
     }
-    if (matchesKey(data, "backspace") && shellMode && editor.getText().length === 0) {
-      // Editor swallows backspace-on-empty; two-step exit: first clears the
-      // private signal, second exits shell mode entirely.
+    if (key.matches("backspace") && shellMode && input.getText().length === 0) {
+      // Two-step exit: first backspace clears the private signal, second exits shell mode.
       if (pendingPrivate) setPendingPrivate(false);
       else setShellMode(false);
       return { consume: true };
     }
-    if (matchesKey(data, "ctrl+c")) {
-      editor.setText("");
+    if (key.matches("ctrl+c")) {
+      input.setText("");
       return { consume: true };
     }
-    if (matchesKey(data, "ctrl+d") && editor.getText().length === 0) {
+    if (key.matches("ctrl+d") && input.getText().length === 0) {
       ctx.quit();
       return { consume: true };
     }
-    if (matchesKey(data, "ctrl+t")) {
+    if (jobControl && key.matches("ctrl+z")) {
+      suspendToShell();
+      return { consume: true };
+    }
+    if (key.matches("ctrl+t")) {
       toggleThinking();
       return { consume: true };
     }
-    if (matchesKey(data, "shift+tab")) {
+    if (key.matches("shift+tab")) {
       const { level, levels, supported } = bus.emitPipe("config:get-thinking", {
         level: "off", levels: [] as string[], supported: true,
       });
@@ -1036,43 +1134,26 @@ export function mountAshi(
       }
       return { consume: true };
     }
-    if (matchesKey(data, "ctrl+o")) {
-      const toggle = (node: Container): void => {
-        for (const child of node.children) {
-          const fn = (child as unknown as { toggleExpanded?: () => void }).toggleExpanded;
-          if (typeof fn === "function") fn.call(child);
-          if (child instanceof Container) toggle(child);
-        }
-      };
-      toggle(chat);
-      tui.requestRender();
+    if (key.matches("ctrl+o")) {
+      for (const e of chatEntries) {
+        if (e.t === "group") e.group.toggleExpanded();
+        else if (e.t === "pair") e.result.toggleExpanded();
+      }
+      app.requestRender();
       return { consume: true };
     }
     return undefined;
   });
 
-  tui.start();
+  app.start();
 
   return {
-    tui,
-    stop: () => { tui.stop(); },
+    stop: () => {
+      process.off("SIGCONT", resumeFromSuspend);
+      app.stop();
+    },
     openTreePicker,
     openSessionPicker,
     rebuildChat,
   };
 }
-
-function isForkAnchor(e: SessionEntry): boolean {
-  if (e.type === "session" || e.type === "compaction") return true;
-  return e.type === "message" && e.message.role === "user";
-}
-
-function pickerLabel(e: SessionEntry, isActive: boolean): string {
-  const marker = isActive ? "●" : "│";
-  const short = e.id.slice(0, 6);
-  if (e.type === "session") return `${marker} ${short} session start`;
-  if (e.type === "compaction") return `${marker} ${short} ▼ compacted (firstKept=${e.firstKeptId.slice(0, 6)})`;
-  const raw = e.type === "message" && typeof e.message.content === "string" ? e.message.content : "";
-  const text = stripContextWrappers(raw).slice(0, 70).replace(/\n/g, " ");
-  return `${marker} ${short} ${text}`;
-}