@ian-pascoe/pi-termctrl 0.5.0 → 0.7.0

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/termctrl-registry.ts

@@ -13,7 +13,7 @@ import type { TerminalViewport } from "./pi-termctrl-settings.js";
 /** The `globalThis` key every registry version shares. Its value always satisfies {@link RegistrySlot}. */
 export const REGISTRY_KEY = Symbol.for("@ian-pascoe/pi-termctrl/registry");
 /** Bump on any change to the state's shape: a reloaded module must not adopt an older shape. */
-export const REGISTRY_VERSION = 5;
+export const REGISTRY_VERSION = 6;
 
 /** Live Terminals plus Background jobs allowed across the whole process. */
 export const LIVE_ENTRY_CAP = 16;
@@ -84,6 +84,11 @@ export interface TerminalEntry extends EntryBase {
    * last lines before the cursor, or, while the cursor is 0, the log's first line.
    */
   logAnchor: readonly string[];
+  /**
+   * The screen rows the agent last received, which start at `logCursor` in the log; `undefined`
+   * marks a row cut from that result. Lines that scroll off unchanged are not reported again.
+   */
+  seenRows: readonly (string | undefined)[];
 }
 
 /** A `bash` command moved to the background. */
@@ -463,6 +468,7 @@ export class TermctrlRegistry {
         lastScreen: undefined,
         logCursor: 0,
         logAnchor: [],
+        seenRows: [],
       };
       this.state.entries.set(id, entry);
       this.syncWatcher();

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);
+}