@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/utility/src/render/spacing.ts

@@ -0,0 +1,235 @@
+/**
+ * @pi-unipi/utility — transcript spacing normalization.
+ *
+ * pi puts a leading Spacer before every chat block, and several block kinds
+ * additionally pad themselves (a tinted box's top/bottom pad, a tool result
+ * that starts with a blank line, hidden-thinking assistant steps that render
+ * only spacing). Two adjacent blocks can then produce 2–4 consecutive blank
+ * rows in the transcript.
+ *
+ * The normalization runs where all of those components meet: the chat
+ * transcript container. Each child renders as usual, its leading/trailing
+ * blank rows are trimmed (OSC-8-aware, via trimEdgeBlankLines), and non-empty
+ * blocks are joined with exactly one blank row — the same single gap pi
+ * intends between blocks, minus the accidental stacking.
+ */
+
+import { isAssistant, trimEdgeBlankLines } from "./reply-bg.js";
+
+/** A block's position inside a run of same-group siblings. */
+export interface SpacingGroupPosition {
+  index: number;
+  count: number;
+  /** spacingKind of the previous / next member of the same group run. */
+  prevKind?: string;
+  nextKind?: string;
+}
+
+/**
+ * Optional marks a transcript child can carry:
+ *  - `spacingGroup` — adjacent visible children sharing the same non-empty
+ *    group are joined with NO separator row (a sidekick run reads as one
+ *    rail block, like the lead's tool tree);
+ *  - `spacingKind` — reported to neighbours as prevKind/nextKind;
+ *  - `setGroupPosition` — called with the member's index/count in the run
+ *    before it renders (so tree connectors can pick ├ vs └).
+ */
+interface Renderable {
+  render(width: number): string[];
+  spacingGroup?: string;
+  spacingKind?: string;
+  setGroupPosition?: (pos: SpacingGroupPosition) => void;
+}
+
+/**
+ * pi's CustomEntryComponent (duck-typed): the host transcript child wraps the
+ * extension's renderer output in `customComponent`, so group metadata lives
+ * one level down. `entry.customType` marks the wrapper even before a render
+ * produced content.
+ */
+export function isCustomEntry(c: unknown): boolean {
+  return !!c && typeof c === "object" && "customComponent" in c &&
+    (c as { entry?: { customType?: unknown } }).entry?.customType !== undefined;
+}
+
+/** Metadata + position hooks, wherever they live (wrapper or legacy direct). */
+interface GroupOwner {
+  spacingGroup?: string;
+  spacingKind?: string;
+  setGroupPosition?: (pos: SpacingGroupPosition) => void;
+}
+
+/**
+ * Resolve the group owner for a transcript child: ONLY an explicit custom
+ * entry (isCustomEntry) unwraps to its inner `customComponent` — an arbitrary
+ * object that merely happens to carry a customComponent field is never
+ * hijacked. Anything else is the legacy path: the child itself carries the
+ * metadata. Nothing is copied: the owner is re-resolved every render so
+ * theme/expansion rebuilds of the inner component are picked up.
+ */
+export function groupOwnerOf(child: unknown): GroupOwner {
+  if (isCustomEntry(child)) {
+    const inner = (child as { customComponent?: unknown }).customComponent;
+    if (inner !== undefined && inner !== null && typeof inner === "object") return inner as GroupOwner;
+  }
+  return (child ?? {}) as GroupOwner;
+}
+
+interface MouseLayout {
+  width: number;
+  children: Array<{ component: unknown; height: number }>;
+}
+
+export interface TranscriptContainer {
+  children: Renderable[];
+  mouseLayout?: MouseLayout;
+  render(width: number): string[];
+}
+
+/** pi's tool-execution component (updateArgs/updateResult pair). */
+function isToolExecution(c: unknown): boolean {
+  const o = c as { updateArgs?: unknown; updateResult?: unknown } | null;
+  return !!o && typeof o.updateArgs === "function" && typeof o.updateResult === "function";
+}
+
+/**
+ * Depth-first search for pi's chat transcript container: the Container whose
+ * children are transcript blocks (assistant messages, tool executions…).
+ * The container is only found once a reply or tool row exists on screen.
+ */
+export function findTranscriptContainer(root: unknown, depth = 0): TranscriptContainer | undefined {
+  if (!root || typeof root !== "object" || depth > 12) return undefined;
+  const children = (root as { children?: unknown[] }).children;
+  if (!Array.isArray(children) || children.length === 0) return undefined;
+  if (children.some((c) => isAssistant(c) || isToolExecution(c) || isCustomEntry(c))) return root as TranscriptContainer;
+  for (const child of children) {
+    const hit = findTranscriptContainer(child, depth + 1);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+const SPACING_PATCHED = Symbol("unipi.transcriptSpacing");
+
+/**
+ * Patch the transcript container: child renders are trimmed at the edges and
+ * non-empty blocks are joined with exactly one blank row. Interior blanks
+ * (inside a reply panel, a box, a diff) are untouched. Idempotent — call it
+ * whenever the tree may have been rebuilt; a fresh container gets re-patched.
+ */
+export function patchTranscriptSpacing(container: TranscriptContainer): void {
+  const flagged = container as TranscriptContainer & Record<symbol, unknown>;
+  if (flagged[SPACING_PATCHED] === true) return;
+  const self = container;
+  // Previous-render group state per child (keyed by child identity): a child
+  // that was in a run last render but isn't anymore gets its position reset
+  // and its rendered rows replaced — otherwise a stale ├ survives a group
+  // removal on persistent (non-rebuilt) owners.
+  const groupedLastRender = new WeakSet<object>();
+  self.render = function render(width: number): string[] {
+    const rendered = self.children.map((child) => ({ child, lines: trimEdgeBlankLines(child.render(width)) }));
+    const visible = rendered.filter((r) => r.lines.length > 0);
+    // Runs of adjacent visible children sharing a spacingGroup: tell every
+    // member's group owner its position (index/count + neighbour kinds), then
+    // re-render the OUTER child — the owner may change its lines (├ vs └ tree
+    // connectors, panel label) and the wrapper owns the transcript row.
+    const members = new Set<object>();
+    let gi = 0;
+    while (gi < visible.length) {
+      const grp = groupOwnerOf(visible[gi]!.child).spacingGroup;
+      if (grp === undefined || grp === "") {
+        gi++;
+        continue;
+      }
+      let end = gi + 1;
+      while (end < visible.length && groupOwnerOf(visible[end]!.child).spacingGroup === grp) end++;
+      const run = visible.slice(gi, end);
+      run.forEach((m, idx) => {
+        const owner = groupOwnerOf(m.child);
+        members.add(m.child);
+        groupedLastRender.add(m.child);
+        if (owner.setGroupPosition === undefined) return;
+        owner.setGroupPosition({
+          index: idx,
+          count: run.length,
+          prevKind: idx > 0 ? groupOwnerOf(run[idx - 1]!.child).spacingKind : undefined,
+          nextKind: idx < run.length - 1 ? groupOwnerOf(run[idx + 1]!.child).spacingKind : undefined,
+        });
+        m.lines = trimEdgeBlankLines(m.child.render(width));
+      });
+      gi = end;
+    }
+    // Group removed since the last render: reset the owner's position and
+    // swap its rendered rows for the post-reset render (├ → └ same tick).
+    for (const r of visible) {
+      if (members.has(r.child) || !groupedLastRender.has(r.child)) continue;
+      const owner = groupOwnerOf(r.child);
+      if (owner.setGroupPosition === undefined) continue;
+      owner.setGroupPosition({ index: 0, count: 1 });
+      r.lines = trimEdgeBlankLines(r.child.render(width));
+      groupedLastRender.delete(r.child);
+    }
+    const lines: string[] = [];
+    const mouseChildren: Array<{ component: unknown; height: number }> = [];
+    let prevGroup: string | undefined;
+    for (const { child, lines: childLines } of rendered) {
+      if (childLines.length === 0) {
+        mouseChildren.push({ component: child, height: 0 });
+        continue;
+      }
+      const grp = groupOwnerOf(child).spacingGroup;
+      const joined = grp !== undefined && grp !== "" && grp === prevGroup;
+      // pi attributes the separator to the child below it (it unshifts ""
+      // into the child's lines); grouped members get no separator.
+      if (lines.length > 0 && !joined) childLines.unshift("");
+      lines.push(...childLines);
+      mouseChildren.push({ component: child, height: childLines.length });
+      prevGroup = grp;
+    }
+    self.mouseLayout = { width, children: mouseChildren };
+    return lines;
+  };
+  flagged[SPACING_PATCHED] = true;
+}
+
+const PROBE_WIDGET = "unipi-spacing-probe";
+
+/**
+ * Find the transcript container and patch it once it exists. Mirrors the
+ * reply-bg probe: a zero-height widget gives us the TUI root; a few timed
+ * retries cover resumed sessions whose history renders right after load.
+ */
+export function installTranscriptSpacing(pi: {
+  on: (event: any, handler: (event: any, ctx?: any) => void) => void;
+}): void {
+  let tui: unknown;
+  const tryPatch = () => {
+    if (tui === undefined) return;
+    try {
+      const container = findTranscriptContainer(tui);
+      if (container !== undefined) patchTranscriptSpacing(container);
+    } catch {
+      /* spacing is cosmetic; never block a render tick */
+    }
+  };
+  try {
+    pi.on("session_start", (_e: any, ctx: any) => {
+      if (!ctx?.hasUI) return;
+      try {
+        ctx.ui.setWidget(
+          PROBE_WIDGET,
+          (t: unknown) => {
+            tui = t;
+            return { invalidate() {}, render: () => [] };
+          },
+          { placement: "belowEditor" },
+        );
+        for (const ms of [0, 400, 2000]) setTimeout(tryPatch, ms);
+      } catch {}
+    });
+    pi.on("message_end", () => setTimeout(tryPatch, 0));
+    pi.on("agent_end", () => setTimeout(tryPatch, 0));
+  } catch {
+    // cosmetic; never block load
+  }
+}

package/packages/utility/src/render/styled.ts

@@ -0,0 +1,251 @@
+/**
+ * @pi-unipi/utility — render-style helpers for activity that isn't a pi tool
+ * call: sidekick steps, subagent transcript items. Foreign calls draw with
+ * the same verbs/markers/gutter the lead's own tools get in the active style:
+ *
+ *   simple    `└ • Ran  npm test · 14 output lines`   (mcode row)
+ *   advanced  `◆ Ran npm test` + `│ ` guttered output tail + `└ Done · 1.2s`
+ *   regular   `◆ bash ls` + a few dim output lines    (pi-fallback look)
+ *
+ * Text (sidekick prose) renders as markdown, `● `-anchored in simple.
+ */
+
+import { getMarkdownTheme, ToolExecutionComponent, type Theme } from "@earendil-works/pi-coding-agent";
+import { Markdown, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { getSettings } from "@pi-unipi/core";
+import {
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createReadToolDefinition,
+  createWriteToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { anchorAssistant, simpleToolLine, verbsFor } from "./simple.js";
+import { readPiToolOptions } from "./pi-settings.js";
+
+export type RenderStyle = "regular" | "advanced" | "simple";
+
+// The style is read on every render tick (transcript entries repaint often);
+// the settings file read behind getSettings is memoized briefly.
+let styleCache: { at: number; cwd: string; value: RenderStyle } | undefined;
+
+/**
+ * The active transcript style (`utility.render.style`). When the utility
+ * extension isn't loaded the namespace isn't registered and the style falls
+ * back to pi's own look ("regular").
+ */
+export function renderStyle(cwd: string = process.cwd()): RenderStyle {
+  const now = Date.now();
+  if (styleCache !== undefined && styleCache.cwd === cwd && now - styleCache.at < 2000) return styleCache.value;
+  let value: RenderStyle = "regular";
+  try {
+    const render = getSettings("utility", cwd).render as { style?: unknown } | undefined;
+    if (render?.style === "simple" || render?.style === "advanced") value = render.style;
+  } catch {
+    /* unregistered namespace or unreadable settings → regular */
+  }
+  styleCache = { at: now, cwd, value };
+  return value;
+}
+
+/** Test/evidence hook: drop the memoized style (e.g. after a settings write). */
+export function resetRenderStyleCache(): void {
+  styleCache = undefined;
+}
+
+/** The fg/bold subset every caller's theme object already provides. */
+export type StyledTheme = Pick<Theme, "fg" | "bold">;
+
+/** pi's duration format (renderers/bash.ts): `1.2s`, `3m 4s`, `1h 2m 3s`. */
+export function formatElapsed(ms: number): string {
+  const seconds = ms / 1000;
+  if (seconds < 1) return `${Math.max(1, Math.round(ms))}ms`;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const totalSeconds = Math.floor(seconds);
+  const minutes = Math.floor(totalSeconds / 60);
+  const remainder = totalSeconds % 60;
+  if (minutes < 60) return `${minutes}m ${remainder}s`;
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m ${remainder}s`;
+}
+
+export interface StyledToolCall {
+  name: string;
+  /** One-line target, already picked/shrunk by the caller ("" when none). */
+  arg: string;
+  /** Full stored output — collapsed views show a tail, expanded all of it. */
+  output: string;
+  isError: boolean;
+  running?: boolean;
+  expanded?: boolean;
+  durationMs?: number;
+  /** Tree connector for the simple row (default `└`). */
+  connector?: "├" | "└";
+}
+
+function outputLines(output: string): string[] {
+  return output.replace(/\s+$/u, "").split("\n").filter((l, i, a) => l.length > 0 || i < a.length - 1);
+}
+
+const SIMPLE_OUTPUT_TAIL = 3;
+const ADVANCED_OUTPUT_TAIL = 5;
+
+/**
+ * A foreign tool call as transcript lines in the active style. Returns []
+ * when there is nothing to show.
+ */
+export function styledToolCallLines(
+  style: RenderStyle,
+  spec: StyledToolCall,
+  theme: StyledTheme,
+  width: number,
+): string[] {
+  const t = theme;
+  const w = Math.max(10, width);
+  const out = spec.output ? outputLines(spec.output) : [];
+
+  if (style === "simple") {
+    const metaBits: string[] = [];
+    if (!spec.running) {
+      if (out.length > 0) metaBits.push(`${String(out.length)} output line${out.length === 1 ? "" : "s"}`);
+      if (spec.durationMs !== undefined) metaBits.push(formatElapsed(spec.durationMs));
+    }
+    const row = simpleToolLine(t as Theme, spec.name, spec.arg, {
+      running: spec.running === true,
+      failed: spec.isError,
+      meta: metaBits.length > 0 ? ` · ${metaBits.join(" · ")}` : "",
+      connector: spec.connector ?? "└",
+      width: w,
+    });
+    const lines = [row];
+    if (spec.expanded === true) {
+      for (const l of out) lines.push(truncateToWidth(`   ${t.fg("toolOutput", l)}`, w));
+    }
+    return lines;
+  }
+
+  if (style === "advanced") {
+    const [runningVerb, doneVerb, failedVerb] = verbsFor(spec.name);
+    const verb = spec.isError ? failedVerb : spec.running === true ? runningVerb : doneVerb;
+    const head = spec.arg !== ""
+      ? `${t.fg("accent", "◆")} ${t.bold(verb)} ${t.fg("accent", spec.arg)}`
+      : `${t.fg("accent", "◆")} ${t.bold(verb)}`;
+    const lines = [truncateToWidth(head, w)];
+    const shown = spec.expanded === true ? out : out.slice(-ADVANCED_OUTPUT_TAIL);
+    if (spec.expanded !== true && out.length > shown.length) {
+      lines.push(truncateToWidth(`${t.fg("muted", "│")} ${t.fg("dim", `… ${String(out.length - shown.length)} earlier lines (ctrl+o)`)}`, w));
+    }
+    for (const l of shown) lines.push(truncateToWidth(`${t.fg("muted", "│")} ${t.fg("toolOutput", l)}`, w));
+    if (spec.durationMs !== undefined || spec.isError) {
+      const label = spec.isError ? "Failed" : "Done";
+      const dur = spec.durationMs !== undefined ? ` · ${formatElapsed(spec.durationMs)}` : "";
+      lines.push(truncateToWidth(`${t.fg("muted", "└")} ${t.fg(spec.isError ? "error" : "dim", `${label}${dur}`)}`, w));
+    }
+    return lines;
+  }
+
+  // regular — the pi-fallback look the entry renderers used before.
+  const mark = spec.isError ? t.fg("error", "✗") : t.fg("accent", "◆");
+  const head = spec.arg !== ""
+    ? `${mark} ${t.fg("toolTitle", t.bold(spec.name))} ${t.fg("accent", spec.arg)}`
+    : `${mark} ${t.fg("toolTitle", t.bold(spec.name))}`;
+  const lines = [truncateToWidth(head, w)];
+  const shown = spec.expanded === true ? out : out.slice(-SIMPLE_OUTPUT_TAIL);
+  if (spec.expanded !== true && out.length > shown.length) {
+    lines.push(t.fg("dim", `… ${String(out.length - shown.length)} earlier lines`));
+  }
+  for (const l of shown) lines.push(truncateToWidth(`  ${t.fg("toolOutput", l)}`, w));
+  return lines;
+}
+
+export interface StyledTextOpts {
+  /** Shown dimmed above the text — only in the expanded view. */
+  thinking?: string;
+}
+
+/**
+ * Foreign assistant-ish text as transcript lines: markdown, `● `-anchored in
+ * simple mode like the lead's prose; expanded thinking renders dimmed first.
+ */
+export function styledTextLines(
+  style: RenderStyle,
+  markdown: string,
+  opts: StyledTextOpts,
+  theme: StyledTheme,
+  width: number,
+): string[] {
+  const t = theme;
+  const w = Math.max(10, width);
+  const lines: string[] = [];
+  if (opts.thinking !== undefined && opts.thinking.trim() !== "") {
+    lines.push(`${t.fg("accent", "◆")} ${t.fg("dim", "thinking")}`);
+    for (const l of opts.thinking.split("\n")) {
+      lines.push(truncateToWidth(`  ${t.fg("dim", l.length > 160 ? `${l.slice(0, 159)}…` : l)}`, w));
+    }
+  }
+  const source = style === "simple" ? anchorAssistant(markdown) : markdown;
+  lines.push(...new Markdown(source, 0, 0, getMarkdownTheme()).render(w));
+  return lines;
+}
+
+/** Convenience wrapper: the styled lines as a pi-tui Component. */
+export function styledComponent(build: (width: number) => string[]): Component {
+  return { invalidate() {}, render: build };
+}
+
+// ─── regular style: pi's own finished-call card ───────────────────────────
+
+/** pi's built-in tool factories — the defs carry the regular renderers. */
+const NATIVE_FACTORIES: Record<string, (cwd: string) => object> = {
+  bash: (cwd) => createBashToolDefinition(cwd, readPiToolOptions(cwd).bash),
+  read: (cwd) => createReadToolDefinition(cwd, readPiToolOptions(cwd).read),
+  edit: (cwd) => createEditToolDefinition(cwd) as object,
+  write: (cwd) => createWriteToolDefinition(cwd) as object,
+  grep: (cwd) => createGrepToolDefinition(cwd) as object,
+  find: (cwd) => createFindToolDefinition(cwd) as object,
+  ls: (cwd) => createLsToolDefinition(cwd) as object,
+};
+
+let nativeStepSeq = 0;
+
+/** A stub TUI for mounted transcript components (they only re-render). */
+const NATIVE_UI = { requestRender() {} };
+
+/**
+ * pi's own ToolExecutionComponent rendering a finished call — identical to
+ * the lead's regular-style tool card. Available only for pi's built-in tools
+ * (their renderers come from the exported def factories) and only when the
+ * step carries its raw args; returns undefined otherwise (caller falls back
+ * to the `◆` lines).
+ */
+export function nativeToolComponent(spec: {
+  name: string;
+  args?: Record<string, unknown>;
+  output: string;
+  isError: boolean;
+  expanded?: boolean;
+}): Component | undefined {
+  const factory = NATIVE_FACTORIES[spec.name];
+  if (factory === undefined || spec.args === undefined) return undefined;
+  try {
+    const cwd = process.cwd();
+    const comp = new ToolExecutionComponent(
+      spec.name,
+      `foreign-step-${++nativeStepSeq}`,
+      spec.args,
+      {},
+      factory(cwd) as never,
+      NATIVE_UI as never,
+      cwd,
+    ) as Component & { updateResult(r: unknown, partial: boolean): void; setExpanded(b: boolean): void };
+    comp.updateResult(
+      { content: spec.output !== "" ? [{ type: "text", text: spec.output }] : [], isError: spec.isError },
+      false,
+    );
+    if (spec.expanded === true) comp.setExpanded(true);
+    return comp;
+  } catch {
+    return undefined;
+  }
+}