@ian-pascoe/pi-termctrl 0.6.0 → 0.7.0

package/README.md

@@ -189,9 +189,16 @@ the session that started the entry, and wait across `/reload`.
 `/ps` opens an overlay listing every entry in the Pi process, including those of
 in-process child agents, with kind, id, owner (`root` or `child`), state and
 age, plus a live preview of the selected Terminal's screen or Background job's
-log tail. Keys: `↑`/`↓` select, `k` stops without confirmation (the agent gets an
-Exit notification), `x` removes an exited entry, `Esc` closes. The footer shows
-`N running` while anything is live. In RPC mode `/ps` sends a one-line summary;
+log tail. It uses Pi's selector frame, with a Status Mark before each entry
+(`●` running, `✓` exited cleanly, `✗` failed, `■` ended by a signal). Keys:
+`↑`/`↓` select, `k` stops without confirmation (the agent gets an Exit
+notification), `x` removes an exited entry, `Esc` closes. The footer shows
+`● termctrl N running` while anything is live.
+
+The `terminal_*` tools render like `bash` in the transcript: a header with the
+tool name and target, the last 5 screen lines (`ctrl+o` expands), and a `Took`
+footer. Exit notifications show one row per exit, marked `✓` for a clean exit and
+`■` otherwise. In RPC mode `/ps` sends a one-line summary;
 print mode has no UI but keeps the tools and notifications.
 
 ## Lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -34,11 +34,12 @@
     "provenance": true
   },
   "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.5.0",
     "@kitlangton/terminal-control": "^1.2.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {

package/src/bash-replacement.ts

@@ -19,6 +19,7 @@ import {
   type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
+import { noticeText } from "@ian-pascoe/pi-utils/ui";
 import { Type, type TSchema } from "typebox";
 import { KILLED_EXIT, TermctrlRegistry } from "./termctrl-registry.js";
 import type { LineByteLimits } from "./pi-termctrl-settings.js";
@@ -264,7 +265,10 @@ export class RunningBashCalls {
       try {
         call.background(this.registry());
       } catch (error) {
-        ui.notify(error instanceof Error ? error.message : String(error), "warning");
+        ui.notify(
+          noticeText("Termctrl", error instanceof Error ? error.message : String(error)),
+          "warning",
+        );
       }
     }
   }

package/src/exit-notification.ts

@@ -1,5 +1,14 @@
 import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
 import { Text, type Component } from "@earendil-works/pi-tui";
+import {
+  COLLAPSED_LINES,
+  customMessageBox,
+  expandHint,
+  joinInline,
+  previewBody,
+  statusMark,
+  summaryExpandHint,
+} from "@ian-pascoe/pi-utils/ui";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import type { ExitNotice } from "./termctrl-registry.js";
@@ -110,19 +119,55 @@ function messageText(content: RenderedMessage["content"]): string {
   return content.map((part) => (part.type === "text" ? part.text : "")).join("");
 }
 
-/** Compact renderer: one line per exit, with the full text when expanded. */
+type MessageTheme = Parameters<ExitNotificationRenderer>[2];
+
+function exitRow(theme: MessageTheme, exit: ExitNotificationDetails["exits"][number]): string {
+  const done = exit.exit_code === 0 && exit.signal === null;
+  const body = (text: string) => theme.fg("customMessageText", text);
+  const status = describeExitStatus({ code: exit.exit_code, signal: exit.signal });
+  return `${statusMark(theme, done ? "done" : "stopped")} ${body(theme.bold(exit.id))} ${joinInline(
+    theme,
+    [body(status), body(formatDuration(exit.duration_ms)), theme.fg("muted", exit.command)],
+  )}`;
+}
+
+/** The Collapsed View's rows: at most 10, then the Expand Hint for the rest or for the full text. */
+function collapsedRows(theme: MessageTheme, rows: readonly string[]): string[] {
+  const hidden = rows.length - COLLAPSED_LINES.fallback;
+  if (hidden > 0) return [...rows.slice(0, COLLAPSED_LINES.fallback), expandHint(theme, hidden)];
+  const last = rows.length - 1;
+  return rows.map((row, index) => (index === last ? `${row}${summaryExpandHint(theme)}` : row));
+}
+
+/** `exit`, or `N exits` when several Terminals or Background jobs ended together. */
+function exitHeading(details: ExitNotificationDetails | undefined): string {
+  const count = Value.Check(ExitNotificationDetailsSchema, details) ? details.exits.length : 1;
+  return count === 1 ? "exit" : `${count} exits`;
+}
+
+/**
+ * Pi's custom-message look: a `customMessageBg` box under a bold `[termctrl] exit` label.
+ * Collapsed, it shows one Status Mark row per exit; expanded, the full text.
+ */
 export const renderExitNotification: ExitNotificationRenderer = (
   message,
   options,
   theme,
 ): Component => {
-  if (options.expanded || !Value.Check(ExitNotificationDetailsSchema, message.details)) {
-    return new Text(theme.fg("muted", messageText(message.content)), options.outputPad, 0);
-  }
-  const lines = message.details.exits.map((exit) => {
-    const failed = exit.exit_code !== 0 || exit.signal !== null;
-    const status = describeExitStatus({ code: exit.exit_code, signal: exit.signal });
-    return `${theme.fg(failed ? "warning" : "success", "■")} ${theme.bold(exit.id)} ${status} · ${formatDuration(exit.duration_ms)} · ${theme.fg("muted", exit.command)}`;
-  });
-  return new Text(lines.join("\n"), options.outputPad, 0);
+  const details = message.details;
+  const rows =
+    !options.expanded && Value.Check(ExitNotificationDetailsSchema, details)
+      ? collapsedRows(
+          theme,
+          details.exits.map((exit) => exitRow(theme, exit)),
+        )
+      : previewBody(theme, messageText(message.content).replace(/\n+$/u, "").split("\n"), {
+          limit: COLLAPSED_LINES.fallback,
+          expanded: options.expanded,
+          color: "customMessageText",
+        });
+  const heading = theme.fg("customMessageText", exitHeading(details));
+  return customMessageBox(theme, { outputPad: options.outputPad, source: "termctrl", heading }, [
+    new Text(rows.join("\n"), 0, 0),
+  ]);
 };

package/src/pi-termctrl-extension.ts

@@ -7,6 +7,7 @@ import {
   type ExtensionFactory,
   type SessionShutdownEvent,
 } from "@earendil-works/pi-coding-agent";
+import { expandMessageOnClick, noticeText } from "@ian-pascoe/pi-utils/ui";
 import { createBashReplacement, RunningBashCalls } from "./bash-replacement.js";
 import {
   EXIT_NOTIFICATION_TYPE,
@@ -84,7 +85,10 @@ class PiTermctrlController {
   }
 
   register(): void {
-    this.pi.registerMessageRenderer(EXIT_NOTIFICATION_TYPE, renderExitNotification);
+    this.pi.registerMessageRenderer(
+      EXIT_NOTIFICATION_TYPE,
+      expandMessageOnClick(renderExitNotification),
+    );
     this.pi.registerCommand("ps", {
       description: "Show and stop Terminals and Background jobs",
       handler: async () => {
@@ -154,7 +158,10 @@ class PiTermctrlController {
     );
     const settings = resolveTermctrlSettings(settingsManager);
     if (settings.warnings.length > 0) {
-      context.ui.notify(`Pi Termctrl settings:\n- ${settings.warnings.join("\n- ")}`, "warning");
+      context.ui.notify(
+        noticeText("Termctrl", `Settings:\n- ${settings.warnings.join("\n- ")}`),
+        "warning",
+      );
     }
     const registry = this.registry;
     const owner = context.sessionManager.getSessionId();
@@ -178,7 +185,10 @@ class PiTermctrlController {
     const commandPrefix = settingsManager.getShellCommandPrefix();
     if (this.binary.kind === "missing") {
       context.ui.notify(
-        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
+        noticeText(
+          "Termctrl",
+          `Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
+        ),
         "warning",
       );
       if (settings.replaceBash) this.registerManagementTools();

package/src/ps-panel.ts

@@ -1,12 +1,27 @@
-import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  DynamicBorder,
+  keyText,
+  type ExtensionContext,
+  type KeybindingsManager,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
 import {
   matchesKey,
-  truncateToWidth,
   visibleWidth,
+  wrapTextWithAnsi,
   type Component,
   type OverlayHandle,
   type TUI,
 } from "@earendil-works/pi-tui";
+import {
+  clipPlain,
+  footerStatus,
+  hintLine,
+  joinInline,
+  noticeText,
+  statusMark,
+  type StatusKind,
+} from "@ian-pascoe/pi-utils/ui";
 import { formatDuration } from "./exit-notification.js";
 import type { TermctrlEntry, TermctrlRegistry } from "./termctrl-registry.js";
 
@@ -40,6 +55,13 @@ function singleLine(text: string): string {
   return text.replaceAll(/\s+/gu, " ").trim();
 }
 
+/** The Status Mark of an entry: running, ended cleanly, ended by a signal, or failed. */
+function markKind(entry: TermctrlEntry): StatusKind {
+  if (entry.state === "running") return "active";
+  if (entry.exit?.signal !== null && entry.exit?.signal !== undefined) return "stopped";
+  return entry.exit?.code === 0 ? "done" : "failed";
+}
+
 /** The live `/ps` overlay: every entry in the process, a preview of the selected one, and stop keys. */
 export class TermctrlPsPanel implements Component {
   private entries: readonly TermctrlEntry[] = [];
@@ -85,40 +107,54 @@ export class TermctrlPsPanel implements Component {
       1,
       Math.min(Math.floor(this.tui.terminal.rows * 0.9), this.tui.terminal.rows - 2 * MARGIN),
     );
-    if (width < 8 || height < 6) {
-      return [truncateToWidth("Esc close · Enlarge terminal", width, "…")];
+    const inner = width - 2;
+    const help = wrapTextWithAnsi(this.hints(), inner);
+    if (width < 8 || height < 8 + help.length) {
+      return wrapTextWithAnsi(this.theme.fg("muted", "Enlarge terminal"), width);
     }
-    const inner = width - 4;
     const now = Date.now();
     const running = this.entries.filter((entry) => entry.state === "running").length;
+    const title = joinInline(this.theme, [
+      this.theme.fg("accent", this.theme.bold("Terminals and Background jobs")),
+      this.theme.fg("muted", `${running} running`),
+    ]);
     const header = [
-      this.theme.bold(`Terminals and Background jobs · ${running} running`),
-      this.theme.fg("warning", this.notice),
+      ...wrapTextWithAnsi(title, inner),
+      ...(this.notice === "" ? [] : wrapTextWithAnsi(this.theme.fg("warning", this.notice), inner)),
     ];
-    const help = [this.theme.fg("dim", "↑↓ select · k stop · x remove exited · esc close")];
-    const listHeight = Math.max(
-      1,
-      Math.min(this.entries.length || 1, Math.floor((height - 6) / 2)),
-    );
+    // Two borders and the blank lines around the title, the list, and the hints.
+    const room = height - 6 - header.length - help.length;
+    const listHeight = Math.max(1, Math.min(this.entries.length || 1, Math.floor(room / 2)));
     const rows =
       this.entries.length === 0
         ? [this.theme.fg("muted", "Nothing is running.")]
         : this.visibleRows(listHeight).map((entry) => this.row(entry, inner, now));
-    const previewHeight = Math.max(0, height - 2 - header.length - rows.length - help.length - 1);
-    const previewLines = this.previewLines(previewHeight);
+    const previewLines = this.previewLines(room - rows.length - 1, inner);
+    const border = new DynamicBorder((text) => this.theme.fg("border", text)).render(width);
     const body = [
+      "",
       ...header,
+      "",
       ...rows,
-      this.theme.fg("border", "─".repeat(inner)),
-      ...previewLines,
+      ...(previewLines.length === 0 ? [] : ["", ...previewLines]),
+      "",
       ...help,
+      "",
     ];
-    const border = (text: string) => this.theme.fg("border", text);
-    const framed = body.map((line) => {
-      const content = truncateToWidth(line, inner, "…");
-      return `${border("│")} ${content}${" ".repeat(Math.max(0, inner - visibleWidth(content)))} ${border("│")}`;
-    });
-    return [border(`╭${"─".repeat(width - 2)}╮`), ...framed, border(`╰${"─".repeat(width - 2)}╯`)];
+    const framed = body.map(
+      (line) => ` ${line}${" ".repeat(Math.max(0, inner - visibleWidth(line)))} `,
+    );
+    return [...border, ...framed, ...border];
+  }
+
+  /** The footer hints, drawn from the injected theme as Pi's selector does. */
+  private hints(): string {
+    return hintLine(this.theme, [
+      { key: "\u2191\u2193", description: "navigate" },
+      { key: "k", description: "stop" },
+      { key: "x", description: "remove exited" },
+      { key: keyText("tui.select.cancel"), description: "close" },
+    ]);
   }
 
   invalidate(): void {}
@@ -163,17 +199,15 @@ export class TermctrlPsPanel implements Component {
             ageOf(entry, now).padStart(6),
           ]
         : [entry.id.padEnd(4), stateLabel(entry).padEnd(9)];
-    const line = `${selected ? ">" : " "} ${columns.join("  ")}  ${singleLine(entry.command)}`;
-    const styled = selected
-      ? this.theme.fg("accent", line)
-      : entry.state === "exited"
-        ? this.theme.fg("muted", line)
-        : line;
-    return truncateToWidth(styled, width, "…");
+    // Pi's selector marks the selected row with `→ `; the Status Mark follows it.
+    const text = clipPlain(`${columns.join("  ")}  ${singleLine(entry.command)}`, width - 4);
+    const color = selected ? "accent" : entry.state === "exited" ? "muted" : "text";
+    const marker = selected ? this.theme.fg("accent", "→ ") : "  ";
+    return `${marker}${statusMark(this.theme, markKind(entry))} ${this.theme.fg(color, text)}`;
   }
 
-  private previewLines(height: number): string[] {
-    if (height <= 0) return [];
+  private previewLines(height: number, width: number): string[] {
+    if (height < 2) return [];
     const selected = this.entries.find((entry) => entry.id === this.selectedId);
     if (selected === undefined) return [];
     const title = this.theme.fg(
@@ -181,7 +215,10 @@ export class TermctrlPsPanel implements Component {
       selected.kind === "terminal" ? `${selected.id} screen` : `${selected.id} log tail`,
     );
     const text = this.preview.replace(/\n+$/u, "");
-    const lines = text === "" ? [this.theme.fg("muted", "(no output yet)")] : text.split("\n");
+    const lines =
+      text === ""
+        ? [this.theme.fg("muted", "(no output yet)")]
+        : text.split("\n").map((line) => this.theme.fg("text", clipPlain(line, width)));
     return [title, ...lines.slice(-(height - 1))];
   }
 
@@ -235,7 +272,7 @@ export class TermctrlPsPanel implements Component {
   private stopSelected(): void {
     const entry = this.entries.find((candidate) => candidate.id === this.selectedId);
     if (entry === undefined || entry.state !== "running") return;
-    this.notice = `Stopping ${entry.id}…`;
+    this.notice = `Stopping ${entry.id}...`;
     void this.registry.stopByUser(entry.id).then(() => {
       if (this.disposed) return;
       this.notice = `Stopped ${entry.id}.`;
@@ -274,7 +311,16 @@ export class TermctrlPsController {
   ) {
     const update = () => {
       const running = registry.runningCount();
-      context.ui.setStatus(STATUS_KEY, running > 0 ? `${running} running` : undefined);
+      context.ui.setStatus(
+        STATUS_KEY,
+        running > 0
+          ? footerStatus(context.ui.theme, {
+              mark: "active",
+              name: "termctrl",
+              value: `${running} running`,
+            })
+          : undefined,
+      );
     };
     this.stopFooter = context.hasUI ? registry.onChange(update) : () => {};
     if (context.hasUI) update();
@@ -322,7 +368,7 @@ export class TermctrlPsController {
         },
       )
       .catch(() => {
-        this.context.ui.notify("The /ps view failed.", "error");
+        this.context.ui.notify(noticeText("Termctrl", "The /ps view failed."), "error");
       })
       .finally(() => {
         this.panel?.dispose();

package/src/terminal-render.ts

@@ -0,0 +1,398 @@
+import { Container, Spacer, Text, type Component } from "@earendil-works/pi-tui";
+import {
+  appendDurationFooter,
+  callDurationFooter,
+  COLLAPSED_LINES,
+  expandHint,
+  joinInline,
+  previewBody,
+  toolHeader,
+  type DurationContext,
+  type UiTheme,
+} from "@ian-pascoe/pi-utils/ui";
+import { describeExitStatus, formatDuration } from "./exit-notification.js";
+import type { ListResult, StopResult, TerminalResult, WaitResult } from "./terminal-tools.js";
+
+type RenderTheme = Pick<UiTheme, "fg" | "bold">;
+
+/** What a result renderer reads from Pi's render context. */
+export interface ResultContext extends DurationContext {
+  readonly isError: boolean;
+}
+
+/** What a result renderer reads from Pi's render options. */
+export interface ResultOptions {
+  readonly expanded: boolean;
+  readonly isPartial: boolean;
+}
+
+interface RenderedResult<TDetails> {
+  readonly content: readonly { readonly type: string; readonly text?: string }[];
+  readonly details: TDetails | undefined;
+}
+
+/** The widest a typed or sent value gets in a call header before it is cut. */
+const ARGUMENT_WIDTH = 60;
+
+function column(...children: Component[]): Container {
+  const container = new Container();
+  for (const child of children) container.addChild(child);
+  return container;
+}
+
+function textBlock(lines: readonly string[]): Component {
+  return new Text(lines.join("\n"), 0, 0);
+}
+
+/** The call row: Pi's header, with the live `Elapsed` footer until a result row takes over. */
+function callRow(
+  theme: RenderTheme & Pick<UiTheme, "fg">,
+  context: DurationContext,
+  header: string,
+): Component {
+  return column(textBlock([header]), callDurationFooter(theme, context));
+}
+
+function quoted(value: string): string {
+  const characters = Array.from(JSON.stringify(value));
+  return characters.length <= ARGUMENT_WIDTH
+    ? characters.join("")
+    : `${characters.slice(0, ARGUMENT_WIDTH - 3).join("")}...`;
+}
+
+function when(condition: boolean, text: string): string | undefined {
+  return condition ? text : undefined;
+}
+
+function joinArguments(parts: readonly (string | undefined)[]): string | undefined {
+  const present = parts.filter((part): part is string => part !== undefined);
+  return present.length === 0 ? undefined : present.join(" ");
+}
+
+/** Arguments of a `terminal_start` call as they stream in, so every one may be absent. */
+export interface StartCallArguments {
+  readonly command?: string;
+  readonly cwd?: string;
+  readonly wait_ms?: number;
+  readonly notify?: boolean;
+}
+
+/** `terminal_start` call row: `terminal_start $ command`, as Pi's bash shows its command. */
+export function renderStartCall(
+  args: StartCallArguments,
+  theme: RenderTheme,
+  context: DurationContext,
+): Component {
+  const command = args.command === undefined ? "..." : args.command;
+  const extra = joinArguments([
+    args.cwd === undefined ? undefined : `in ${args.cwd}`,
+    args.wait_ms === undefined ? undefined : `wait ${args.wait_ms}ms`,
+    when(args.notify === false, "no notify"),
+  ]);
+  return callRow(theme, context, toolHeader(theme, "terminal_start", `$ ${command}`, extra));
+}
+
+/** Arguments of a `terminal_send` call as they stream in. */
+export interface SendCallArguments {
+  readonly id?: string;
+  readonly text?: string;
+  readonly keys?: readonly string[];
+  readonly wait_for_text?: string;
+  readonly wait_ms?: number;
+}
+
+/** `terminal_send` call row: the Terminal id, then what is typed, pressed and waited for. */
+export function renderSendCall(
+  args: SendCallArguments,
+  theme: RenderTheme,
+  context: DurationContext,
+): Component {
+  const text = args.text ?? "";
+  const keys = args.keys ?? [];
+  const extra = joinArguments([
+    text === "" ? undefined : `type ${quoted(text)}`,
+    keys.length === 0 ? undefined : `press ${keys.join(" ")}`,
+    args.wait_for_text === undefined ? undefined : `wait_for ${quoted(args.wait_for_text)}`,
+    args.wait_ms === undefined ? undefined : `${args.wait_ms}ms`,
+    when(text === "" && keys.length === 0 && args.wait_for_text === undefined, "poll"),
+  ]);
+  return callRow(theme, context, toolHeader(theme, "terminal_send", args.id ?? "...", extra));
+}
+
+/** `terminal_stop` call row. */
+export function renderStopCall(
+  args: { readonly id?: string },
+  theme: RenderTheme,
+  context: DurationContext,
+): Component {
+  return callRow(theme, context, toolHeader(theme, "terminal_stop", args.id ?? "..."));
+}
+
+/** `terminal_wait` call row: the ids it waits for, or every running entry. */
+export function renderWaitCall(
+  args: { readonly ids?: readonly string[]; readonly wait_ms?: number },
+  theme: RenderTheme,
+  context: DurationContext,
+): Component {
+  const ids = args.ids === undefined || args.ids.length === 0 ? undefined : args.ids.join(" ");
+  const extra = args.wait_ms === undefined ? undefined : `${args.wait_ms}ms`;
+  return callRow(theme, context, toolHeader(theme, "terminal_wait", ids, extra));
+}
+
+/** `terminal_list` takes no arguments. */
+export type ListCallArguments = Readonly<Record<never, never>>;
+
+/** `terminal_list` call row. */
+export function renderListCall(
+  _args: ListCallArguments,
+  theme: RenderTheme,
+  context: DurationContext,
+): Component {
+  return callRow(theme, context, toolHeader(theme, "terminal_list"));
+}
+
+function contentText(content: RenderedResult<unknown>["content"]): string {
+  return content.map((part) => (part.type === "text" ? (part.text ?? "") : "")).join("");
+}
+
+/** Pi's result layout, as its bash renderer builds it: a blank line, the body, then the footer. */
+function resultRow(
+  theme: RenderTheme,
+  context: ResultContext,
+  options: ResultOptions,
+  body: readonly string[],
+): Component {
+  const container = new Container();
+  if (body.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(body.join("\n"), 0, 0));
+  }
+  appendDurationFooter(container, theme, context, { isPartial: options.isPartial });
+  return container;
+}
+
+function errorRow(
+  theme: RenderTheme,
+  context: ResultContext,
+  options: ResultOptions,
+  result: RenderedResult<unknown>,
+): Component {
+  const lines = contentText(result.content).trim().split("\n");
+  return resultRow(
+    theme,
+    context,
+    options,
+    previewBody(theme, lines, {
+      limit: COLLAPSED_LINES.fallback,
+      expanded: options.expanded,
+      color: "error",
+    }),
+  );
+}
+
+function warning(theme: RenderTheme, text: string): string {
+  return theme.fg("warning", `[${text}]`);
+}
+
+function splitLines(text: string | undefined): string[] {
+  if (text === undefined || text === "") return [];
+  return text.replace(/\n+$/u, "").split("\n");
+}
+
+function screenLines(screen: string): string[] {
+  const lines = splitLines(screen);
+  return lines.length === 0 ? ["(blank)"] : lines;
+}
+
+/**
+ * A Terminal's lines in bash's Collapsed View, the last 5 with the earlier lines counted in the
+ * Expand Hint. The Expanded View labels the scrolled-off lines apart from the screen.
+ */
+function terminalBody(
+  theme: RenderTheme,
+  expanded: boolean,
+  scrolledOff: readonly string[],
+  screen: readonly string[],
+): string[] {
+  const styled = (lines: readonly string[]) => lines.map((line) => theme.fg("toolOutput", line));
+  if (!expanded) {
+    return previewBody(theme, [...scrolledOff, ...screen], {
+      limit: COLLAPSED_LINES.terminal,
+      expanded,
+      keep: "end",
+    });
+  }
+  if (scrolledOff.length === 0) return styled(screen);
+  return [
+    theme.fg("muted", "--- scrolled off ---"),
+    ...styled(scrolledOff),
+    theme.fg("muted", "--- screen ---"),
+    ...styled(screen),
+  ];
+}
+
+function terminalWarnings(
+  theme: RenderTheme,
+  details: Pick<TerminalResult, "output_missing" | "full_output_path">,
+): string[] {
+  const warnings: string[] = [];
+  if (details.output_missing === true) warnings.push(warning(theme, "Earlier output is missing"));
+  if (details.full_output_path !== undefined) {
+    warnings.push(warning(theme, `Full output: ${details.full_output_path}`));
+  }
+  return warnings;
+}
+
+function exitText(details: Pick<TerminalResult, "state" | "exit_code" | "signal">): string {
+  return details.state === "running"
+    ? "running"
+    : describeExitStatus({ code: details.exit_code ?? null, signal: details.signal ?? null });
+}
+
+function isFailedExit(details: Pick<TerminalResult, "state" | "exit_code" | "signal">): boolean {
+  return details.state === "exited" && (details.exit_code !== 0 || details.signal !== undefined);
+}
+
+/** `terminal_start` and `terminal_send` result: a status line, then the screen like bash output. */
+export function renderTerminalResult(
+  result: RenderedResult<TerminalResult>,
+  options: ResultOptions,
+  theme: RenderTheme,
+  context: ResultContext,
+): Component {
+  const details = result.details;
+  if (context.isError || details === undefined) return errorRow(theme, context, options, result);
+  const status = joinInline(theme, [
+    theme.fg(isFailedExit(details) ? "warning" : "muted", `${details.id} ${exitText(details)}`),
+    theme.fg("muted", `settled: ${details.settle_reason}`),
+    details.changed ? undefined : theme.fg("muted", "screen unchanged"),
+  ]);
+  const body = terminalBody(
+    theme,
+    options.expanded,
+    splitLines(details.scrolled_off),
+    screenLines(details.screen),
+  );
+  return resultRow(theme, context, options, [status, ...body, ...terminalWarnings(theme, details)]);
+}
+
+/** `terminal_stop` result: the stop line, then the final screen or the job's recent output. */
+export function renderStopResult(
+  result: RenderedResult<StopResult>,
+  options: ResultOptions,
+  theme: RenderTheme,
+  context: ResultContext,
+): Component {
+  const details = result.details;
+  if (context.isError || details === undefined) return errorRow(theme, context, options, result);
+  const status = theme.fg("muted", contentText(result.content).split("\n")[0] ?? "");
+  const body =
+    details.kind === "terminal"
+      ? terminalBody(
+          theme,
+          options.expanded,
+          splitLines(details.scrolled_off),
+          splitLines(details.screen),
+        )
+      : terminalBody(theme, options.expanded, [], splitLines(details.output));
+  return resultRow(theme, context, options, [status, ...body, ...terminalWarnings(theme, details)]);
+}
+
+/** A list in ls's Collapsed View: its first 20 rows and the Expand Hint for the rest. */
+function listRows(theme: RenderTheme, rows: readonly string[], expanded: boolean): string[] {
+  const hidden = rows.length - COLLAPSED_LINES.list;
+  if (expanded || hidden <= 0) return [...rows];
+  return [...rows.slice(0, COLLAPSED_LINES.list), expandHint(theme, hidden)];
+}
+
+function entryRow(
+  theme: RenderTheme,
+  entry: {
+    id: string;
+    command: string;
+    state: string;
+    exit_code?: number | undefined;
+    signal?: string | undefined;
+  },
+  ageSeconds: number,
+): string {
+  const state =
+    entry.state === "running"
+      ? "running"
+      : describeExitStatus({ code: entry.exit_code ?? null, signal: entry.signal ?? null });
+  return `${theme.fg("accent", entry.id)} ${joinInline(theme, [
+    theme.fg("toolOutput", state),
+    theme.fg("muted", formatDuration(ageSeconds * 1000)),
+    theme.fg("toolOutput", entry.command),
+  ])}`;
+}
+
+/** `terminal_list` result: one row per Terminal and Background job, like ls. */
+export function renderListResult(
+  result: RenderedResult<ListResult>,
+  options: ResultOptions,
+  theme: RenderTheme,
+  context: ResultContext,
+): Component {
+  const details = result.details;
+  if (context.isError || details === undefined) return errorRow(theme, context, options, result);
+  const rows = [
+    ...details.terminals.map((entry) => entryRow(theme, entry, entry.age_seconds)),
+    ...details.background_jobs.map((entry) => {
+      const row = entryRow(theme, entry, entry.age_seconds);
+      return options.expanded ? `${row} ${theme.fg("muted", `(log ${entry.log_path})`)}` : row;
+    }),
+  ];
+  const body =
+    rows.length === 0 ? [theme.fg("muted", "(none)")] : listRows(theme, rows, options.expanded);
+  return resultRow(theme, context, options, body);
+}
+
+const WAIT_REASON_SUMMARY = {
+  exited: undefined,
+  timeout: "Nothing exited before the wait ended",
+  message: "Returned early: a message is waiting",
+  aborted: "Wait cancelled",
+  nothing_running: "Nothing to wait for",
+} as const satisfies Record<WaitResult["reason"], string | undefined>;
+
+/**
+ * `terminal_wait` result: what exited and what still runs, one row each. The Expanded View adds
+ * each exit's last lines.
+ */
+export function renderWaitResult(
+  result: RenderedResult<WaitResult>,
+  options: ResultOptions,
+  theme: RenderTheme,
+  context: ResultContext,
+): Component {
+  const details = result.details;
+  if (context.isError || details === undefined) return errorRow(theme, context, options, result);
+  const summary = WAIT_REASON_SUMMARY[details.reason];
+  const rows: string[] = [];
+  for (const exit of details.exited) {
+    const status = describeExitStatus({
+      code: exit.exit_code ?? null,
+      signal: exit.signal ?? null,
+    });
+    rows.push(
+      `${theme.fg("accent", exit.id)} ${joinInline(theme, [
+        theme.fg("toolOutput", status),
+        theme.fg("muted", formatDuration(exit.duration_ms)),
+        theme.fg("toolOutput", exit.command),
+      ])}`,
+    );
+    if (options.expanded) {
+      for (const line of splitLines(exit.output)) rows.push(`  ${theme.fg("toolOutput", line)}`);
+      if (exit.log_path !== undefined) rows.push(theme.fg("muted", `  Log: ${exit.log_path}`));
+    }
+  }
+  for (const entry of details.running) {
+    rows.push(entryRow(theme, { ...entry, state: "running" }, entry.age_seconds));
+  }
+  const body = [
+    ...(summary === undefined ? [] : [theme.fg("muted", summary)]),
+    ...listRows(theme, rows, options.expanded),
+  ];
+  return resultRow(theme, context, options, body);
+}

package/src/terminal-tools.ts

@@ -20,6 +20,17 @@ import { describeExitStatus, formatExitNotice, lastLines } from "./exit-notifica
 import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
 import type { LineByteLimits, TerminalViewport } from "./pi-termctrl-settings.js";
 import type { TerminalExit, TerminalSnapshot } from "./terminal-driver.js";
+import {
+  renderListCall,
+  renderListResult,
+  renderSendCall,
+  renderStartCall,
+  renderStopCall,
+  renderStopResult,
+  renderTerminalResult,
+  renderWaitCall,
+  renderWaitResult,
+} from "./terminal-render.js";
 import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 /** Screen quiet period that settles a Terminal. */
@@ -112,7 +123,7 @@ const TerminalResultSchema = Type.Object({
     }),
   ),
 });
-type TerminalResult = Static<typeof TerminalResultSchema>;
+export type TerminalResult = Static<typeof TerminalResultSchema>;
 
 const ListEntrySchema = Type.Object({
   id: Type.String(),
@@ -128,7 +139,7 @@ const ListResultSchema = Type.Object({
     Type.Object({ ...ListEntrySchema.properties, log_path: Type.String() }),
   ),
 });
-type ListResult = Static<typeof ListResultSchema>;
+export type ListResult = Static<typeof ListResultSchema>;
 
 const StopResultSchema = Type.Object({
   id: Type.String(),
@@ -166,7 +177,7 @@ const StopResultSchema = Type.Object({
   ),
   output: Type.Optional(Type.String({ description: "Background job only: its recent output" })),
 });
-type StopResult = Static<typeof StopResultSchema>;
+export type StopResult = Static<typeof StopResultSchema>;
 
 const WaitMsSchema = Type.Optional(
   Type.Integer({ minimum: 0, description: "Maximum milliseconds to wait (clamped to 300000)" }),
@@ -268,7 +279,7 @@ const WaitResultSchema = Type.Object({
     }),
   ),
 });
-type WaitResult = Static<typeof WaitResultSchema>;
+export type WaitResult = Static<typeof WaitResultSchema>;
 type WaitReason = WaitResult["reason"];
 
 /** Clamp a requested wait to the fixed 0 to 5 minute range. */
@@ -837,6 +848,8 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
       openWorldHint: true,
     },
     outputSchema: TerminalResultSchema,
+    renderCall: renderStartCall,
+    renderResult: renderTerminalResult,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const cwd = await resolveWorkingDirectory(context.cwd, params.cwd);
       const entry = await runtime.registry.startTerminal(ownerOf(context), {
@@ -894,6 +907,8 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
       openWorldHint: true,
     },
     outputSchema: TerminalResultSchema,
+    renderCall: renderSendCall,
+    renderResult: renderTerminalResult,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const entry = runtime.registry.find(ownerOf(context), params.id);
       if (entry === undefined) throw unknownId(params.id);
@@ -1004,6 +1019,8 @@ export function createTerminalStopTool({ registry, scrollback }: TerminalResultR
       openWorldHint: false,
     },
     outputSchema: StopResultSchema,
+    renderCall: renderStopCall,
+    renderResult: renderStopResult,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const owner = ownerOf(context);
       const known = registry.find(owner, params.id);
@@ -1166,6 +1183,8 @@ export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
       openWorldHint: false,
     },
     outputSchema: WaitResultSchema,
+    renderCall: renderWaitCall,
+    renderResult: renderWaitResult,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const owner = ownerOf(context);
       const targets = waitTargets(registry, owner, params.ids);
@@ -1238,6 +1257,8 @@ export function createTerminalListTool(registry: TermctrlRegistry) {
       openWorldHint: false,
     },
     outputSchema: ListResultSchema,
+    renderCall: renderListCall,
+    renderResult: renderListResult,
     async execute(_toolCallId, _params, _signal, _onUpdate, context) {
       const now = Date.now();
       const entries = registry.ownedEntries(ownerOf(context));