@pi-archimedes/core 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -16,15 +16,19 @@
     "./chrome": "./src/chrome.ts",
     "./text": "./src/text.ts",
     "./color": "./src/color.ts",
+    "./overlay": "./src/overlay.ts",
     "./config": "./src/config.ts",
     "./settings-io": "./src/settings-io.ts",
-    "./profiler": "./src/profiler.ts"
+    "./profiler": "./src/profiler.ts",
+    "./tool-render": "./src/tool-render.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { TUI, type EditorTheme, type Component, type SettingItem } from "@earendil-works/pi-tui";
+import { type TUI, type EditorTheme, type Component, type SettingItem } from "@earendil-works/pi-tui";
 
 import { HephaestusEditor } from "./editor/index.js";
 

package/src/overlay.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import {
+  visibleWidth,
+  padEnd,
+  wrapText,
+  hardTruncate,
+  renderHeader,
+  renderFooter,
+  wrapWithBorder,
+  borderContentWidth,
+  OVERLAY_CHROME,
+  type OverlayTheme,
+} from "./overlay.js";
+
+// Mock theme: fg returns its text argument untouched.
+const mockTheme: OverlayTheme = {
+  fg: (_color: string, text: string) => text,
+};
+
+// Mock theme that records the color token passed to fg.
+function recordingTheme() {
+  let lastColor: string | null = null;
+  const theme: OverlayTheme = {
+    fg: (color: string, text: string) => {
+      lastColor = color;
+      return text;
+    },
+  };
+  return { theme, lastColor: () => lastColor };
+}
+
+// ── visibleWidth ─────────────────────────────────────────────────────────────
+
+describe("visibleWidth", () => {
+  it("counts a plain string", () => {
+    expect(visibleWidth("hello")).toBe(5);
+  });
+
+  it("ignores ANSI SGR codes", () => {
+    expect(visibleWidth("\x1b[31mred\x1b[0m")).toBe(3);
+  });
+
+  it("returns 0 for empty string", () => {
+    expect(visibleWidth("")).toBe(0);
+  });
+});
+
+// ── padEnd ───────────────────────────────────────────────────────────────────
+
+describe("padEnd", () => {
+  it("pads to width", () => {
+    expect(padEnd("hi", 5)).toBe("hi   ");
+  });
+
+  it("returns input unchanged when visible width >= target", () => {
+    expect(padEnd("hello", 5)).toBe("hello");
+    expect(padEnd("toolong", 5)).toBe("toolong");
+  });
+
+  it("returns '' for width <= 0", () => {
+    expect(padEnd("text", 0)).toBe("");
+    expect(padEnd("text", -3)).toBe("");
+  });
+});
+
+// ── wrapText ─────────────────────────────────────────────────────────────────
+
+describe("wrapText", () => {
+  it("wraps a long line to width", () => {
+    expect(wrapText("aaa bbb ccc ddd", 8)).toEqual(["aaa bbb ", "ccc ddd"]);
+  });
+
+  it("wraps long words to width", () => {
+    expect(wrapText("hello world", 5)).toEqual(["hello", " ", "world"]);
+  });
+
+  it("preserves empty paragraphs as blank lines", () => {
+    expect(wrapText("one\n\ntwo", 10)).toEqual(["one", "", "two"]);
+  });
+
+  it("returns [] for width <= 0", () => {
+    expect(wrapText("anything", 0)).toEqual([]);
+  });
+});
+
+// ── hardTruncate ─────────────────────────────────────────────────────────────
+
+describe("hardTruncate", () => {
+  it("leaves short strings alone", () => {
+    expect(hardTruncate("short", 10)).toBe("short");
+  });
+
+  it("truncates at the visible-width boundary", () => {
+    expect(hardTruncate("hello world", 5)).toBe("hello");
+  });
+
+  it("truncates an ANSI-colored string and appends a reset", () => {
+    const result = hardTruncate("\x1b[31mhello world\x1b[0m", 5);
+    expect(result).toBe("\x1b[31mhello\x1b[0m");
+    expect(result).toContain("\x1b[0m");
+  });
+});
+
+// ── renderHeader / renderFooter ──────────────────────────────────────────────
+
+describe("renderHeader", () => {
+  it("pads to width and renders with the accent token", () => {
+    const { theme, lastColor } = recordingTheme();
+    const out = renderHeader(" Title ", 10, theme);
+    expect(out).toBe(" Title    ");
+    expect(lastColor()).toBe("accent");
+  });
+});
+
+describe("renderFooter", () => {
+  it("pads to width and renders with the dim token", () => {
+    const { theme, lastColor } = recordingTheme();
+    const out = renderFooter(" hint ", 10, theme);
+    expect(out).toBe(" hint     ");
+    expect(lastColor()).toBe("dim");
+  });
+});
+
+// ── wrapWithBorder / borderContentWidth ──────────────────────────────────────
+
+describe("borderContentWidth", () => {
+  it("derives content width from outer width", () => {
+    expect(borderContentWidth(84)).toBe(80);
+  });
+
+  it("floors at 1 for tiny widths", () => {
+    expect(borderContentWidth(0)).toBe(1);
+    expect(borderContentWidth(2)).toBe(1);
+  });
+});
+
+describe("wrapWithBorder", () => {
+  const W = 84;
+
+  it("emits border rows with the correct shape", () => {
+    const out = wrapWithBorder(["a", "b"], W, mockTheme);
+    expect(out[0]).toBe("┌" + "─".repeat(W - 2) + "┐");
+    expect(out[out.length - 1]).toBe("└" + "─".repeat(W - 2) + "┘");
+    expect(out[1]).toBe("│ a" + " ".repeat(W - 4) + "│");
+    expect(out[2]).toBe("│ b" + " ".repeat(W - 4) + "│");
+  });
+
+  it("emits exactly lines.length + 2 rows", () => {
+    const out = wrapWithBorder(["a", "b", "c"], W, mockTheme);
+    expect(out.length).toBe(5);
+  });
+
+  it("pads every row to exactly the outer width", () => {
+    const out = wrapWithBorder(["x", "shorter", "y"], W, mockTheme);
+    for (const line of out) {
+      expect(visibleWidth(line)).toBe(W);
+    }
+  });
+
+  it("hard-truncates content wider than the content width, without overflowing", () => {
+    const long = "z".repeat(W + 10); // wider than the 80-col content area
+    const out = wrapWithBorder([long], W, mockTheme);
+    expect(out.length).toBe(3);
+    for (const line of out) {
+      expect(visibleWidth(line)).toBe(W);
+    }
+    expect(out[1]).toBe("│ " + "z".repeat(W - 4) + " │");
+  });
+});
+
+// ── OVERLAY_CHROME ───────────────────────────────────────────────────────────
+
+describe("OVERLAY_CHROME", () => {
+  it("matches the /agents overlay options", () => {
+    expect(OVERLAY_CHROME).toEqual({
+      anchor: "center",
+      width: 84,
+      maxHeight: "80%",
+    });
+  });
+});

package/src/overlay.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared overlay chrome — border wrapping, text width math, header/footer
+ * rendering. Used by the /agents manager (subagent) and the /archimedes
+ * settings overlay (meta) so both screens look identical.
+ */
+
+/** Minimal structural theme — anything with `fg` satisfies it (the real pi-coding-agent Theme, agent-manager's local interface, or a test mock). */
+export interface OverlayTheme {
+  fg(token: string, text: string): string;
+}
+
+export function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [];
+  const lines: string[] = [];
+  const paragraphs = text.split("\n");
+  for (const para of paragraphs) {
+    if (para.length === 0) {
+      lines.push("");
+      continue;
+    }
+    const words = para.split(/(\s+)/).filter(Boolean);
+    let current = "";
+    for (const word of words) {
+      const test = current === "" ? word : current + word;
+      if (test.length > width && current.length > 0) {
+        lines.push(current);
+        current = word;
+      } else {
+        current = test;
+      }
+    }
+    if (current) lines.push(current);
+  }
+  return lines;
+}
+
+export function padEnd(text: string, width: number): string {
+  if (width <= 0) return "";
+  const vw = visibleWidth(text);
+  if (vw >= width) return text;
+  return text + " ".repeat(width - vw);
+}
+
+export function visibleWidth(text: string): number {
+  // Strip ANSI escape sequences for width calculation
+  return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+export function renderHeader(text: string, width: number, theme: OverlayTheme): string {
+  return theme.fg("accent", padEnd(text, width));
+}
+
+export function renderFooter(text: string, width: number, theme: OverlayTheme): string {
+  return theme.fg("dim", padEnd(text, width));
+}
+
+/** Content width available inside wrapWithBorder at a given outer width.
+ *  inner = max(1, width - 2); content = max(1, inner - 2). */
+export function borderContentWidth(width: number): number {
+  const innerWidth = Math.max(1, width - 2);
+  return Math.max(1, innerWidth - 2);
+}
+
+/** Shared overlay options so /agents and /archimedes never drift. */
+export const OVERLAY_CHROME = { anchor: "center", width: 84, maxHeight: "80%" } as const;
+
+// ── Border wrapper ────────────────────────────────────────────────────────────
+
+/** Hard-truncate by visible width — no "..." suffix. Strips ANSI, truncates, rebuilds. */
+export function hardTruncate(text: string, maxVisible: number): string {
+  if (visibleWidth(text) <= maxVisible) return text;
+  // Walk the string, skipping ANSI escape sequences, and stop after
+  // maxVisible visible characters; copy SGR codes through so styling survives,
+  // and append a reset at the end so styling doesn't bleed.
+  let result = "";
+  let plainPos = 0;
+  let i = 0;
+  let copiedSgr = false;
+  while (i < text.length && plainPos < maxVisible) {
+    if (text[i] === "\x1b" && text[i + 1] === "[") {
+      // Copy the escape sequence
+      let j = i;
+      while (j < text.length && text[j] !== "m") j++;
+      result += text.slice(i, j + 1);
+      copiedSgr = true;
+      i = j + 1;
+    } else {
+      result += text[i];
+      plainPos++;
+      i++;
+    }
+  }
+  // Ensure styling doesn't bleed: append reset if we copied SGR and result doesn't end with one
+  if (copiedSgr && !/\x1b\[0?m$/.test(result)) {
+    result += "\x1b[0m";
+  }
+  return result;
+}
+
+export function wrapWithBorder(lines: string[], width: number, theme: OverlayTheme): string[] {
+  const innerWidth = Math.max(1, width - 2);
+  const contentWidth = Math.max(1, innerWidth - 2); // minus 1 space padding each side
+  const left = theme.fg("dim", "│");
+  const right = theme.fg("dim", "│");
+  const top = theme.fg("dim", `┌${"─".repeat(innerWidth)}┐`);
+  const bottom = theme.fg("dim", `└${"─".repeat(innerWidth)}┘`);
+  const result: string[] = [top];
+  for (const line of lines) {
+    const clamped = hardTruncate(line, contentWidth);
+    const padded = " " + padEnd(clamped, contentWidth) + " ";
+    result.push(left + padded + right);
+  }
+  result.push(bottom);
+  return result;
+}

package/src/startup/index.ts

@@ -4,7 +4,7 @@ import { loadCoreConfig } from "../config.js";
 import { detectSection, parseSectionText, parseModelScope, formatColumns, buildItemWrapper, type ParsedSection, SECTION_KEYS } from "./sections.js";
 import { fetchLatestVersion, compareVersions } from "./version.js";
 import { stripAnsi } from "../text.js";
-import { Text, Spacer, Container, TUI, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { Text, Spacer, Container, type TUI, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
 
 // Symbol keys (survive hot-reload)
 const LISTING_REF = Symbol.for("splashscreen:listingRef");

package/src/text.ts

@@ -29,7 +29,7 @@ export function clampLine(line: string, maxW: number): string {
 }
 
 /** Clamp an array of lines to maxW visible characters each. */
-export function clampLines(lines: string[], maxW: number): string[] {
+function clampLines(lines: string[], maxW: number): string[] {
   return lines.map((l) => clampLine(l, maxW));
 }
 

package/src/thinking/patch.test.ts

@@ -196,6 +196,54 @@ describe("patchThinkingRenderer", () => {
 		expect(MockClassV2.prototype[PATCH_VERSION_KEY]).toBe("2.0.0");
 	});
 
+	it("accepts a minified thinking-check variant (no whitespace around ===)", async () => {
+		const MockClass = function AssistantMessageComponent() {};
+		MockClass.prototype.updateContent = function updateContent() {
+			// Minified dist-chunk shape: no whitespace around ===, single quotes
+			const content = { type: "thinking" };
+			if (content.type==="thinking") {
+				this.markdownTheme.codeBlockIndent="";
+			}
+		};
+
+		vi.doMock("@earendil-works/pi-coding-agent", () => ({
+			AssistantMessageComponent: MockClass,
+			VERSION: "1.0.0",
+			highlightCode: vi.fn(),
+		}));
+
+		const patch = await importPatch();
+		patch(() => ({} as any));
+
+		// The minification-safe regex probe must accept the minified variant
+		expect(MockClass.prototype[PATCHED_KEY]).toBe(true);
+	});
+
+	it("rejects a negated thinking check", async () => {
+		const MockClass = function AssistantMessageComponent() {};
+		MockClass.prototype.updateContent = function updateContent() {
+			// pi 0.84.3's own minified chunk contains
+			// `thinkingContent.type!=="thinking"` (inner batch-loop break). A source whose
+			// ONLY thinking-relations are negations must NOT pass the probe.
+			const content = { type: "thinking" };
+			if (content.type!=="thinking") {
+				this.markdownTheme.codeBlockIndent="";
+			}
+		};
+
+		vi.doMock("@earendil-works/pi-coding-agent", () => ({
+			AssistantMessageComponent: MockClass,
+			VERSION: "1.0.0",
+			highlightCode: vi.fn(),
+		}));
+
+		const patch = await importPatch();
+		patch(() => ({} as any));
+
+		// PATCHED_KEY must NOT be set — the probe must not match `!==`
+		expect(MockClass.prototype[PATCHED_KEY]).toBeUndefined();
+	});
+
 	it("re-patches on same version to update getTheme closure", async () => {
 		const MockClass = function AssistantMessageComponent() {};
 		MockClass.prototype.updateContent = function updateContent() {

package/src/thinking/patch.ts

@@ -30,7 +30,13 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
   }
 
   const src = proto.updateContent.toString();
-  const hasThinkingCheck = src.includes('content.type === "thinking"');
+  // NOTE: pi ships the interactive TUI in a minified bundle chunk at runtime, so
+  // the source we see via .toString() can be `content.type==="thinking"` (no
+  // spaces) even where dist is readable. The probe below must therefore be
+  // minification-safe: a whitespace-tolerant regex rather than an exact
+  // substring. A bare `space === "thinking"` (or any other field) still does
+  // not match, as required.
+  const hasThinkingCheck = /content\.type\s*===\s*["']thinking["']/.test(src);
   const hasMarkdownTheme = src.includes("this.markdownTheme");
   if (!hasThinkingCheck || !hasMarkdownTheme) {
     console.warn(
@@ -55,9 +61,25 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
     }
   }
 
-  // Re-patch every time — /resume needs a fresh getTheme closure
-  (proto as any).updateContent = function (this: any, message: any): void {
+  // Re-patched every session_start — /resume needs a fresh getTheme closure.
+  //
+  // Shape: 0.84.3 pi native updateContent:
+  //   updateContent(message, isStreaming = this.isStreaming) {
+  //     this.lastMessage = message;
+  //     this.isStreaming = isStreaming;
+  //     this.contentContainer.clear();
+  //     ...
+  //     // batches consecutive "thinking" parts into thinkingBlocks
+  //     //   (skipping empties), i-- after the inner loop,
+  //     //   renders as ONE Markdown section of thinkingBlocks.join("\n\n")
+  //     // or ONE static Text label when hidden.
+  //     // stop-reason: const hasToolCalls = content.some(...);
+  //     //   this.hasToolCalls = hasToolCalls; (render() uses for OSC-133 zones)
+  //     //   stopReason === "length" → Spacer + "truncated" Text
+  //     //   else if (!hasToolCalls) { aborted / error branches }
+  (proto as any).updateContent = function (this: any, message: any, isStreaming?: boolean): void {
     this.lastMessage = message;
+    if (isStreaming !== undefined) this.isStreaming = isStreaming;
 
     this.markdownTheme.codeBlockIndent = "";
     this.contentContainer.clear();
@@ -105,11 +127,11 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
     // We must preserve it here, otherwise those transformers are silently
     // dropped when this patch replaces updateContent.
     //
-    // NOTE: the `transform` option was added to @earendil-works/pi-tui in
-    // 0.84.1. The repo's lockfile pins 0.78.0 whose types lack the field, so we
-    // extend the options type locally; at runtime the field is ignored by very
-    // old pi-tui and honored by 0.84.1+ (which is where Mermaid rendering and
-    // the bug both exist).
+    // NOTE: `createMarkdownTransform` is not exported from pi-coding-agent, so
+    // we inline an equivalent pipeline over `this.markdownTransformers`.
+    //
+    // The `transform` option was added to @earendil-works/pi-tui in 0.84.1.
+    // At runtime older pi-tui ignores the field, 0.84.1+ honors it.
     type MarkdownOptionsWithTransform = MarkdownOptions & {
       transform?: (markdown: string, availableWidth: number) => string;
     };
@@ -139,14 +161,27 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
         this.contentContainer.addChild(
           new Markdown(
             content.text.trim(),
-            1,
+            this.outputPad ?? 1,
             0,
             this.markdownTheme,
             undefined,
             { transform: transformFor("assistant") } as MarkdownOptionsWithTransform,
           ),
         );
-      } else if (content.type === "thinking" && content.thinking.trim()) {
+      } else if (content.type === "thinking") {
+        // Batch a consecutive run of thinking parts into one section
+        // (mirrors 0.84.3 pi native behaviour: thinkBlocks, i-- on the
+        // inner loop, early continue on zero-length runs).
+        const thinkBlocks: string[] = [];
+        for (; i < message.content.length; i++) {
+          const thinkingPart = message.content[i];
+          if (thinkingPart.type !== "thinking") break;
+          const trimmed = thinkingPart.thinking.trim();
+          if (trimmed) thinkBlocks.push(trimmed);
+        }
+        i--;
+        if (thinkBlocks.length === 0) continue;
+
         const hasVisibleContentAfter = message.content
           .slice(i + 1)
           .some(
@@ -156,16 +191,17 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
           );
 
         if (this.hideThinkingBlock) {
+          // One static label for the whole run when hidden.
           const t = ensureTheme();
           if (!t) continue;
           this.contentContainer.addChild(
-            new Text(t.italic(t.fg("thinkingText", this.hiddenThinkingLabel)), 1, 0),
+            new Text(t.italic(t.fg("thinkingText", this.hiddenThinkingLabel)), this.outputPad ?? 1, 0),
           );
           if (hasVisibleContentAfter) {
             this.contentContainer.addChild(new Spacer(1));
           }
         } else {
-          let thinkingContent = content.thinking.trim();
+          let thinkingContent = thinkBlocks.join("\n\n");
           if (!thinkingContent.startsWith(THINKING_LABEL)) {
             thinkingContent = `${THINKING_LABEL}\n\n${thinkingContent}`;
           }
@@ -175,7 +211,7 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
           this.contentContainer.addChild(
             new Markdown(
               thinkingContent,
-              1,
+              this.outputPad ?? 1,
               0,
               muted ?? this.markdownTheme,
               {
@@ -192,9 +228,19 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
       }
     }
 
-    // Aborted/error rendering.
+    // Stop-reason handling — 0.84.3 pi shape. `hasToolCalls` is required by
+    // the component's render() for OSC-133 prompt zones, so it must be set.
     const hasToolCalls = message.content.some((c: any) => c.type === "toolCall");
-    if (!hasToolCalls) {
+    this.hasToolCalls = hasToolCalls;
+
+    if (message.stopReason === "length") {
+      this.contentContainer.addChild(new Spacer(1));
+      const t = ensureTheme();
+      if (t)
+        this.contentContainer.addChild(
+          new Text(t.fg("error", "Response was truncated before completion."), this.outputPad ?? 1, 0),
+        );
+    } else if (!hasToolCalls) {
       if (message.stopReason === "aborted") {
         const abortMessage =
           message.errorMessage && message.errorMessage !== "Request was aborted"
@@ -202,21 +248,18 @@ export function patchThinkingRenderer(getTheme: () => Theme): void {
             : "Operation aborted";
         this.contentContainer.addChild(new Spacer(1));
         const t = ensureTheme();
-        if (t) this.contentContainer.addChild(new Text(t.fg("error", abortMessage), 1, 0));
+        if (t) this.contentContainer.addChild(new Text(t.fg("error", abortMessage), this.outputPad ?? 1, 0));
       } else if (message.stopReason === "error") {
         const errorMsg = message.errorMessage || "Unknown error";
         this.contentContainer.addChild(new Spacer(1));
         const t = ensureTheme();
         if (t) {
           this.contentContainer.addChild(
-            new Text(t.fg("error", `Error: ${errorMsg}`), 1, 0),
+            new Text(t.fg("error", `Error: ${errorMsg}`), this.outputPad ?? 1, 0),
           );
         }
       }
     }
-
-    // Bottom padding so next message has breathing room
-    this.contentContainer.addChild(new Spacer(1));
   };
 
   // Mark as patched with version for incompatibility detection

package/src/tool-render.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import {
+  renderToolHeader,
+  renderStatusLabel,
+  renderToolCallLine,
+  STATUS_GLYPH,
+  type ToolRenderTheme,
+} from "./tool-render.js";
+
+// Fake theme: wraps text in visible markers so assertions can verify tokens.
+const theme: ToolRenderTheme = {
+  fg: (token: string, text: string) => `[${token}:${text}]`,
+  bold: (text: string) => `**${text}**`,
+};
+
+describe("renderToolHeader", () => {
+  it("renders blue bold tool name + orange action", () => {
+    expect(renderToolHeader("mcp", "atlassian", theme)).toBe(
+      "[toolTitle:**mcp**] [accent:atlassian]",
+    );
+  });
+
+  it("renders the name only when action is empty", () => {
+    expect(renderToolHeader("todo", "", theme)).toBe("[toolTitle:**todo**]");
+    expect(renderToolHeader("todo", undefined, theme)).toBe(
+      "[toolTitle:**todo**]",
+    );
+  });
+});
+
+describe("renderStatusLabel", () => {
+  it("running: muted glyph + muted label", () => {
+    expect(renderStatusLabel("running", "2/4 completed", theme)).toBe(
+      "[muted:▸ ][muted:2/4 completed]",
+    );
+  });
+
+  it("success: green glyph + muted label", () => {
+    expect(renderStatusLabel("success", "done", theme)).toBe(
+      "[success:✓ ][muted:done]",
+    );
+  });
+
+  it("error: red glyph + muted label", () => {
+    expect(renderStatusLabel("error", "boom", theme)).toBe(
+      "[error:✗ ][muted:boom]",
+    );
+  });
+
+  it("exposes the glyph map", () => {
+    expect(STATUS_GLYPH).toEqual({ running: "▸", success: "✓", error: "✗" });
+  });
+});
+
+describe("renderToolCallLine", () => {
+  it("success: green glyph + green name + dim suffix", () => {
+    expect(renderToolCallLine("success", "read", ": /path", theme)).toBe(
+      "[success:✓ ][success:read][dim:: /path]",
+    );
+  });
+
+  it("error: red glyph + red name + dim suffix", () => {
+    expect(renderToolCallLine("error", "read", ": /missing", theme)).toBe(
+      "[error:✗ ][error:read][dim:: /missing]",
+    );
+  });
+
+  it("running: muted glyph + muted name", () => {
+    expect(renderToolCallLine("running", "grep", ": pattern | 2s", theme)).toBe(
+      "[muted:▸ ][muted:grep][dim:: pattern | 2s]",
+    );
+  });
+
+  it("omits the dim fragment when suffix is empty", () => {
+    expect(renderToolCallLine("success", "bash", "", theme)).toBe(
+      "[success:✓ ][success:bash]",
+    );
+  });
+});

package/src/tool-render.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared tool-row rendering helpers.
+ *
+ * Archimedes tools (mcp, todo, …) render a consistent two-part row:
+ *
+ *   line 1 (header):  <toolName> (blue bold) + <action> (orange accent)
+ *   result line:      <glyph> <label>  — glyph reflects run status:
+ *                       ▸ running (muted) · ✓ success (green) · ✗ error (red)
+ *                     the label is muted so the glyph carries the colour.
+ *
+ * These helpers are pure (no TUI component imports) so they stay directly
+ * unit-testable and can be reused across packages. Callers wrap the returned
+ * string in whatever component they use (typically a pi-tui Text).
+ */
+
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Run status of a settled/in-flight tool row. */
+export type ToolStatus = "running" | "success" | "error";
+
+/** Glyph shown before the result label, keyed by status. */
+export const STATUS_GLYPH: Record<ToolStatus, string> = {
+  running: "▸",
+  success: "✓",
+  error: "✗",
+};
+
+/** Theme color token used to colour each status glyph. */
+const STATUS_TOKEN: Record<ToolStatus, ThemeColor> = {
+  running: "muted",
+  success: "success",
+  error: "error",
+};
+
+/**
+ * The subset of a pi Theme these helpers need. Typed with pi's ThemeColor so
+ * pi's real Theme is assignable (parameter contravariance: a fn requiring the
+ * wider string token would NOT accept a Theme whose fg only takes ThemeColor).
+ */
+export type ToolRenderTheme = {
+  fg: (token: ThemeColor, text: string) => string;
+  bold: (text: string) => string;
+};
+
+/**
+ * Render the tool header line:
+ *   <toolName> (toolTitle, bold) + " " + <action> (accent)
+ *
+ * When action is empty/undefined only the tool name is rendered.
+ */
+export function renderToolHeader(
+  toolName: string,
+  action: string | undefined,
+  theme: ToolRenderTheme,
+): string {
+  const name = theme.fg("toolTitle", theme.bold(toolName));
+  if (!action) return name;
+  return name + " " + theme.fg("accent", action);
+}
+
+/**
+ * Render a status result line:
+ *   <glyph> (status-coloured) + <label> (muted)
+ *
+ * e.g. "✓ atlassian_searchJiraIssuesUsingJql" or "▸ 2/4 completed".
+ */
+export function renderStatusLabel(
+  status: ToolStatus,
+  label: string,
+  theme: ToolRenderTheme,
+): string {
+  return (
+    theme.fg(STATUS_TOKEN[status], STATUS_GLYPH[status] + " ") +
+    theme.fg("muted", label)
+  );
+}
+
+/**
+ * Render a tool-call line with a status glyph, a status-coloured name, and an
+ * optional dim args/suffix fragment:
+ *
+ *   <glyph> (status-coloured) + <name> (status-coloured) + <suffix> (dim)
+ *
+ * e.g. "✓ read: /path/to/file" (green glyph+name, dim ": /path...") or
+ *      "▸ grep: pattern" (muted glyph+name while running).
+ *
+ * The name shares the glyph's colour (unlike renderStatusLabel, which mutes
+ * the label) so a completed call reads as a single green/red unit. The suffix
+ * is passed pre-formatted (e.g. ": args" or ": args | 2s") and rendered dim.
+ */
+export function renderToolCallLine(
+  status: ToolStatus,
+  name: string,
+  suffix: string,
+  theme: ToolRenderTheme,
+): string {
+  const token = STATUS_TOKEN[status];
+  const head =
+    theme.fg(token, STATUS_GLYPH[status] + " ") + theme.fg(token, name);
+  return suffix ? head + theme.fg("dim", suffix) : head;
+}