omp-claude-tui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack-01041202
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# omp-claude-tui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude Code-style transcript for [omp](https://omp.sh): `● Tool(arg)` cards with a
+`⎿` result gutter, a fullscreen scroll mode with omp's own input docked at the
+bottom, and in-app drag-to-copy.
+
+> **Compatibility:** tested on omp **18.16.0** only. omp has no public API for
+> this, so the plugin hooks omp internals (see [How it works / risk](#how-it-works--risk)).
+> On another omp version a feature may stop working; it then falls back to omp's
+> own look instead of crashing, and `/cc-tui status` shows what is unavailable.
+
+```
+● Bash(seq 1 10)
+  ⎿  1
+     2
+     3
+     4
+     … +6 lines (ctrl+o to expand)
+
+● Update(notes.txt)
+  ⎿  Updated notes.txt with 1 addition and 1 removal
+     1   alpha
+     2 - beta
+     2 + BETA
+     3   gamma
+```
+
+## Install
+
+```sh
+omp plugin install omp-claude-tui
+# or straight from GitHub:
+omp plugin install github:Jack-01041202/omp-claude-tui
+```
+
+Restart omp afterwards; already-open sessions keep their look. Then optionally:
+
+```
+/cc-tui fullscreen on    # start every session in fullscreen scroll mode
+```
+
+Update with `omp plugin upgrade omp-claude-tui`, remove with
+`omp plugin uninstall omp-claude-tui`.
+
+For development, link a checkout instead: `omp plugin link ~/omp-claude-tui`.
+
+## What it changes
+
+| Surface | Result |
+|---|---|
+| `bash` | `● Bash(cmd)`, output under `⎿`, omp's exit/wall-time notices removed, `Exit code N` on failure |
+| `write` | `Wrote N lines to path` plus numbered preview |
+| `edit`, `apply_patch` | `Updated path with N additions and M removals` plus diff |
+| `grep`, `glob`, `find` | `Search(...)` / `Find(...)` with `Found N …`; listing on Ctrl+O |
+| `todo` | `Update Todos` checklist (`☐` / `☒`) |
+| `read` (URL reads only) | `Read N lines` |
+| Working row | `<current intent>… (12s)` |
+| Composer | omp's built-in `claude` shape, only when `composer.shape` is not configured |
+| Input position | pinned to the bottom row even while the transcript is shorter than the screen (blank rows padded on top) |
+
+Bullet: dim while pending, blinking while running, green on success, red on failure.
+
+Not changed: plain file reads (omp draws them in its own grouped read card), `task`
+(live subagent cards use the tool's own renderer), MCP and other tools, the footer
+(`setFooter` is a no-op in omp's interactive mode), and Tern's native view.
+
+## Scroll mode
+
+omp renders the main session inline, so scrolling the terminal back moves the
+input away with everything else. Press `PgUp` (or run `/cc-tui scroll`) to open
+a fullscreen view: the session transcript scrolls on top, and omp's own input
+editor stays docked at the bottom — the same editor instance, so slash and agent
+command completion, `@` files, history, the status line and Enter behave as in
+the normal view.
+
+| Key | Action |
+|---|---|
+| Mouse wheel, `PgUp` / `PgDn` | scroll the transcript (scrolling to the bottom resumes following new output) |
+| Drag | select text in the transcript; copies to the clipboard on release |
+| Double-click / triple-click | select and copy a word / a line |
+| `Ctrl+O` | expand tool output in the transcript |
+| `Esc` | close an open completion menu, otherwise return to the normal view |
+| any other key | goes to the input editor (and clears the selection) |
+
+Copying uses `pbcopy` on macOS and OSC 52 elsewhere; the key hint row briefly
+shows `Copied N characters`. Selection covers the transcript rows on screen
+(no auto-scroll while dragging); scrolling clears it. Holding `Shift` still
+gives the terminal's native selection.
+
+When omp opens a dialog (approval, `ask`, a selector), scroll mode closes and the
+dialog appears in the normal view.
+
+### Default fullscreen
+
+`/cc-tui fullscreen on` makes scroll mode the default, saved across launches:
+every session (startup, `/new`, resume, fork) opens in it, and after a dialog is
+answered the view comes back on its own. `Esc` switches to the normal view until
+the next session starts; `PgUp` returns. `/cc-tui fullscreen off` restores the
+normal view as default and closes the view.
+
+Limits: new text appears once each message is saved to the session file, not
+token by token; needs a saved session (not `--no-session`). `PgUp` no longer
+pages a multi-line draft in the normal editor.
+
+## Command
+
+```
+/cc-tui status        current state
+/cc-tui scroll        open scroll mode (same as PgUp)
+/cc-tui fullscreen on|off  make scroll mode the default for every session (default off)
+/cc-tui on | off      toggle (applies to new and repainted cards)
+/cc-tui lines <n>     rows shown under ⎿ while collapsed (default 4)
+/cc-tui pin on|off    pin the input to the bottom row (default on)
+```
+
+Settings persist in `~/.omp/agent/omp-claude-tui.json`.
+
+## How it works / risk
+
+omp exposes no public API for restyling built-in tool cards. The plugin wraps
+entries of omp's internal renderer registry (`toolRenderers` from
+`@oh-my-pi/pi-tui/tools`). This is display-only: tool definitions the model sees,
+approval and execution are untouched. Each wrapped hook falls back to omp's
+original renderer when it throws or the plugin is off. An omp upgrade that
+changes the registry or the args/details shapes can revert cards to omp's look;
+if the registry is missing, the plugin warns at session start and stays inert.
+
+The bottom pin wraps omp's internal `Composer.prototype.renderFrame` (from
+`@oh-my-pi/pi-tui/prompt/composer`) and pads short frames with blank rows on top.
+If that module is missing, `/cc-tui status` reports `pin input unavailable`.
+With `tui.mouse` on, clicks on live subagent rows can land a few rows off while
+the frame is padded, since omp hit-tests against the unpadded frame.
+
+Scroll mode mounts omp's internal fullscreen transcript viewer
+(`@oh-my-pi/pi-tui/overlays/agent-transcript-viewer`, the one Agent Hub uses)
+read-only on the main session file, parsed with
+`@oh-my-pi/pi-coding-agent/modes/agent-hub-runtime`, and docks the live editor
+taken from omp's composer (recorded by the `renderFrame` wrapper). While open it
+wraps `tui.setFocus` to leave the view when focus moves to a dialog. If a module
+is missing, `/cc-tui status` reports `scroll mode unavailable`.
+Native fullscreen support is tracked upstream in
+[can1357/oh-my-pi#10232](https://github.com/can1357/oh-my-pi/issues/10232).

package/index.ts

@@ -0,0 +1,338 @@
+/**
+ * omp-claude-tui: Claude Code-style transcript for omp.
+ *
+ * Tool cards: wraps entries of omp's internal built-in renderer registry
+ * (`toolRenderers` from `@oh-my-pi/pi-tui/tools`). Display-only — model-facing
+ * tool definitions, approval and execution are untouched. Every wrapped hook
+ * falls back to omp's original renderer when ours throws or the plugin is off.
+ *
+ * Also: a live working-row label and the built-in `claude` composer shape
+ * (pinned only while the user has not configured `composer.shape`).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { lookup } from "@oh-my-pi/pi-coding-agent/config/registry";
+import { type ToolRenderer, toolRenderers } from "@oh-my-pi/pi-tui/tools";
+import { createScrollMode } from "./src/scroll-mode";
+import { type ClaudeRenderer, createRenderers, type NoticeStrippers } from "./src/tools";
+
+const ORIGINAL = Symbol.for("omp-claude-tui.original");
+const ORIGINAL_FRAME = Symbol.for("omp-claude-tui.renderFrame");
+const CONFIG_PATH = path.join(os.homedir(), ".omp", "agent", "omp-claude-tui.json");
+const DEFAULT_PREVIEW_LINES = 4;
+/** `/cc-tui` arguments shown in the completion menu; `"<sub> on"` forms appear once the subcommand is typed. */
+const CC_TUI_ARGS: readonly (readonly [value: string, description: string])[] = [
+	["scroll", "Open scroll mode (fullscreen, input pinned at the bottom); same as PgUp"],
+	["fullscreen", "Default fullscreen: every session opens in scroll mode"],
+	["fullscreen on", "Make fullscreen the default and enter it now"],
+	["fullscreen off", "Stop defaulting to fullscreen and return to the normal view"],
+	["on", "Enable the plugin (Claude-style tool cards, working row)"],
+	["off", "Disable the plugin and restore omp's native look"],
+	["lines", "Rows shown under ⎿ while tool output is collapsed, e.g. lines 6"],
+	["pin", "Push the input to the bottom when the transcript is shorter than the screen"],
+	["pin on", "Pin the input to the bottom"],
+	["pin off", "Stop pinning the input to the bottom"],
+	["status", "Show current settings"],
+];
+
+interface Config {
+	enabled: boolean;
+	previewLines: number;
+	/** Keep the input on the bottom row while the transcript is shorter than the screen. */
+	pinInput: boolean;
+	/** Default fullscreen: every session starts in scroll mode and returns to it after dialogs. */
+	fullscreen: boolean;
+}
+
+function loadConfig(): Config {
+	const config: Config = { enabled: true, previewLines: DEFAULT_PREVIEW_LINES, pinInput: true, fullscreen: false };
+	try {
+		const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")) as Partial<Config>;
+		if (typeof raw.enabled === "boolean") config.enabled = raw.enabled;
+		if (typeof raw.previewLines === "number" && raw.previewLines >= 1) config.previewLines = Math.floor(raw.previewLines);
+		if (typeof raw.pinInput === "boolean") config.pinInput = raw.pinInput;
+		if (typeof raw.fullscreen === "boolean") config.fullscreen = raw.fullscreen;
+	} catch {
+		// Missing or unreadable config: defaults.
+	}
+	return config;
+}
+
+function saveConfig(config: Config): void {
+	fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+	fs.writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, "\t")}\n`);
+}
+
+type Wrapped = ToolRenderer & { [ORIGINAL]?: ToolRenderer };
+
+/**
+ * Replace each registry entry with a delegating wrapper. Wrappers are built from
+ * the pristine renderer (kept under ORIGINAL), so a plugin reload re-wraps
+ * instead of stacking wrappers. Returns the names actually wrapped.
+ */
+function install(renderers: Record<string, ClaudeRenderer>, config: Config): string[] {
+	const installed: string[] = [];
+	for (const [name, ours] of Object.entries(renderers)) {
+		const current = toolRenderers[name] as Wrapped | undefined;
+		const base = current?.[ORIGINAL] ?? current;
+		if (!base || typeof base.renderCall !== "function" || typeof base.renderResult !== "function") continue;
+		const wrapped: Wrapped = {
+			...base,
+			renderCall(args, options, theme) {
+				if (!config.enabled) return base.renderCall(args, options, theme);
+				try {
+					return ours.renderCall(args, options, theme);
+				} catch {
+					return base.renderCall(args, options, theme);
+				}
+			},
+			renderResult(result, options, theme, args) {
+				if (!config.enabled) return base.renderResult(result, options, theme, args);
+				try {
+					return ours.renderResult(result, options, theme, args);
+				} catch {
+					return base.renderResult(result, options, theme, args);
+				}
+			},
+		};
+		// Read at render time by omp, so toggling the plugin applies to existing cards on their next repaint.
+		Object.defineProperties(wrapped, {
+			// Our result component redraws the header, so it can carry the status color.
+			mergeCallAndResult: { get: () => (config.enabled ? true : base.mergeCallAndResult), enumerable: true },
+			// No background box: Claude-style rows sit in the response flow.
+			inline: { get: () => (config.enabled ? true : base.inline), enumerable: true },
+			// The running bullet blinks on the shared spinner tick.
+			animatedPendingPreview: { get: () => (config.enabled ? true : base.animatedPendingPreview), enumerable: true },
+			animatedPartialResult: { get: () => (config.enabled ? true : base.animatedPartialResult), enumerable: true },
+		});
+		wrapped[ORIGINAL] = base;
+		toolRenderers[name] = wrapped;
+		installed.push(name);
+	}
+	return installed;
+}
+
+/**
+ * omp's own notice strippers, when its module resolves inside this omp build.
+ * Dynamic on purpose: `tools/output-meta` is an internal subpath that a future
+ * omp build may drop, and a failed static import would fail the whole plugin load.
+ */
+async function loadStrippers(): Promise<NoticeStrippers> {
+	try {
+		const mod: NoticeStrippers = await import("@oh-my-pi/pi-tui/tools/output-meta");
+		return { stripOutputNotice: mod.stripOutputNotice, stripRawOutputArtifactNotice: mod.stripRawOutputArtifactNotice };
+	} catch {
+		return {};
+	}
+}
+
+/** Pins the built-in `claude` composer shape unless the user configured one. */
+function composerShape(pi: ExtensionAPI): (enabled: boolean) => void {
+	const handle = lookup("composer.shape");
+	const scope = pi.pi.settings;
+	let pinned = false;
+	return enabled => {
+		if (!handle) return;
+		try {
+			if (enabled && !pinned && !handle.isConfigured(scope)) {
+				handle.override(scope, "claude");
+				pinned = true;
+			} else if (!enabled && pinned) {
+				handle.clearOverride(scope);
+				pinned = false;
+			}
+		} catch {
+			// Unknown setting shape in this omp build: leave the composer alone.
+		}
+	};
+}
+
+function formatElapsed(ms: number): string {
+	const s = Math.floor(ms / 1000);
+	return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+/** Working-row label `<intent>… (12s)`, re-applied after omp swaps in each tool intent. */
+function workingRow(pi: ExtensionAPI, config: Config): void {
+	let start = 0;
+	let intent: string | undefined;
+	let active = false;
+	const label = () => `${intent ?? "Working"}… (${formatElapsed(Date.now() - start)})`;
+	// omp's interactive controller accepts a live label function; the declared type is string.
+	const apply = (ctx: ExtensionContext) => {
+		if (active && config.enabled && ctx.hasUI) ctx.ui.setWorkingMessage(label as unknown as string);
+	};
+	pi.on("agent_start", (_event, ctx) => {
+		start = Date.now();
+		intent = undefined;
+		active = true;
+		apply(ctx);
+	});
+	pi.on("tool_execution_start", (event, ctx) => {
+		const next = event.intent?.trim().replace(/\.+$/, "");
+		if (next) intent = next;
+		apply(ctx);
+	});
+	pi.on("agent_end", (_event, ctx) => {
+		active = false;
+		if (config.enabled && ctx.hasUI) ctx.ui.setWorkingMessage();
+	});
+}
+
+interface FrameViewport {
+	readonly columns: number;
+	readonly rows: number;
+}
+interface FramePlan {
+	readonly viewport: readonly string[];
+}
+type RenderFrame = (this: unknown, viewport: FrameViewport) => FramePlan;
+
+/** The composer omp is painting with, recorded on each frame; scroll mode docks its editor and status line. */
+let liveComposer: { readonly editor?: unknown; readonly ui?: { readonly children?: readonly unknown[] } } | undefined;
+
+/**
+ * The composer's status-line slot (host · model · cwd · branch). omp keeps it in a
+ * private field but always mounts it as the TUI's last root (`Composer` re-adds it
+ * after every `setRuntimeChildren`); it is the only root with a `setComponent` slot.
+ */
+function liveStatusLine(): unknown {
+	const children = liveComposer?.ui?.children ?? [];
+	const last = children.at(-1);
+	return last && typeof last === "object" && "setComponent" in last && "render" in last ? last : undefined;
+}
+
+/**
+ * Pin the input to the bottom row. omp paints its live area (transcript tail,
+ * editor, status) directly below whatever the terminal held at startup, so a
+ * short session leaves the input mid-screen; once content fills the screen omp
+ * already keeps it on the bottom row. Padding a short frame with blank rows on
+ * top pushes it down to the bottom row in that remaining case.
+ *
+ * Dynamic on purpose: `prompt/composer` is an internal subpath; a failed static
+ * import would fail the whole plugin load. Returns false when unavailable.
+ */
+async function pinInput(config: Config): Promise<boolean> {
+	let proto: Record<PropertyKey, unknown>;
+	try {
+		const mod: { Composer?: { prototype: Record<PropertyKey, unknown> } } = await import(
+			"@oh-my-pi/pi-tui/prompt/composer"
+		);
+		if (!mod.Composer) return false;
+		proto = mod.Composer.prototype;
+	} catch {
+		return false;
+	}
+	// Wrap the pristine method so a plugin reload does not stack wrappers.
+	const original = (proto[ORIGINAL_FRAME] ?? proto.renderFrame) as RenderFrame | undefined;
+	if (typeof original !== "function") return false;
+	proto[ORIGINAL_FRAME] = original;
+	proto.renderFrame = function (this: NonNullable<typeof liveComposer>, viewport: FrameViewport): FramePlan {
+		liveComposer = this;
+		const plan = original.call(this, viewport);
+		if (!config.enabled || !config.pinInput) return plan;
+		const rows = viewport.rows;
+		const lines = plan.viewport;
+		if (lines.length === 0 || lines.length >= rows) return plan;
+		return { ...plan, viewport: [...Array<string>(rows - lines.length).fill(""), ...lines] };
+	};
+	return true;
+}
+
+/**
+ * One settings object for the whole process. omp re-runs the factory for every
+ * subagent session, while the hooks it installs (renderer registry, composer
+ * prototype) are process-global; each run re-installs them over its own `config`,
+ * so sharing it keeps `/cc-tui` in the main session in charge of what is drawn.
+ */
+let sharedConfig: Config | undefined;
+
+export default async function ompClaudeTui(pi: ExtensionAPI): Promise<void> {
+	const config = (sharedConfig ??= loadConfig());
+	const strippers = await loadStrippers();
+	const renderers = createRenderers({ previewLines: () => config.previewLines }, strippers);
+	const installed = install(renderers, config);
+	const applyComposer = composerShape(pi);
+	applyComposer(config.enabled);
+	workingRow(pi, config);
+	const pinned = await pinInput(config);
+	const scrollMode = await createScrollMode(pi, {
+		mainEditor: () => liveComposer?.editor,
+		mainStatusLine: liveStatusLine,
+		isDefault: () => config.enabled && config.fullscreen,
+	});
+
+	// Opening resolves when the view closes; report a failure instead of leaving it unhandled.
+	const openScrollMode = (ctx: ExtensionContext) => {
+		scrollMode.open(ctx).catch((error: unknown) => {
+			ctx.ui.notify(`omp-claude-tui: scroll mode failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+		});
+	};
+
+	// PgUp opens scroll mode, as it scrolls Claude Code's fullscreen transcript.
+	// It takes over the editor's PgUp, which otherwise only pages a multi-line draft.
+	pi.registerShortcut("pageUp", {
+		description: "Scroll the transcript (fullscreen view, input stays at the bottom)",
+		handler: openScrollMode,
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		if (installed.length === 0) {
+			ctx.ui.notify("omp-claude-tui: omp's renderer registry has an unknown shape; using native rendering", "warning");
+		}
+	});
+
+	pi.registerCommand("cc-tui", {
+		description: "Claude-style transcript: scroll | fullscreen on|off | on | off | lines <n> | pin on|off | status",
+		getArgumentCompletions: prefix =>
+			CC_TUI_ARGS.filter(([value]) => value.startsWith(prefix) && (prefix.includes(" ") || !value.includes(" "))).map(
+				([value, description]) => ({ value, label: value, description }),
+			),
+		handler: async (args, ctx) => {
+			const [cmd = "status", value] = args.trim().split(/\s+/);
+			if (cmd === "scroll") {
+				openScrollMode(ctx);
+				return;
+			}
+			if (cmd === "on" || cmd === "off") {
+				config.enabled = cmd === "on";
+				applyComposer(config.enabled);
+				if (!config.enabled && ctx.hasUI) ctx.ui.setWorkingMessage();
+			} else if (cmd === "lines") {
+				const n = Number(value);
+				if (!Number.isInteger(n) || n < 1) {
+					ctx.ui.notify("Usage: /cc-tui lines <positive integer>", "error");
+					return;
+				}
+				config.previewLines = n;
+			} else if (cmd === "pin") {
+				if (value !== "on" && value !== "off") {
+					ctx.ui.notify("Usage: /cc-tui pin on|off", "error");
+					return;
+				}
+				config.pinInput = value === "on";
+			} else if (cmd === "fullscreen") {
+				if (value !== "on" && value !== "off") {
+					ctx.ui.notify("Usage: /cc-tui fullscreen on|off", "error");
+					return;
+				}
+				config.fullscreen = value === "on";
+				saveConfig(config);
+				if (config.fullscreen) openScrollMode(ctx);
+				else await scrollMode.close();
+				return;
+			} else if (cmd !== "status") {
+				ctx.ui.notify("Usage: /cc-tui scroll | fullscreen on|off | on | off | lines <n> | pin on|off | status", "error");
+				return;
+			}
+			if (cmd !== "status") saveConfig(config);
+			const pin = pinned ? (config.pinInput ? "on" : "off") : "unavailable";
+			ctx.ui.notify(
+				`omp-claude-tui: ${config.enabled ? "on" : "off"} · preview ${config.previewLines} lines · pin input ${pin} · scroll mode ${scrollMode.available ? `PgUp, default ${config.fullscreen ? "on" : "off"}` : "unavailable"} · tools: ${installed.join(", ") || "none"}${cmd === "status" ? "" : " (new tool cards; scroll-back keeps its look)"}`,
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -1,6 +1,19 @@
 {
-  "name": "omp-claude-tui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "omp-claude-tui",
+	"version": "0.1.0",
+	"description": "Claude Code-style transcript, fullscreen scroll mode and in-app copy for omp (oh-my-pi)",
+	"type": "module",
+	"license": "MIT",
+	"author": "Jack-01041202",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Jack-01041202/omp-claude-tui.git"
+	},
+	"homepage": "https://github.com/Jack-01041202/omp-claude-tui#readme",
+	"bugs": "https://github.com/Jack-01041202/omp-claude-tui/issues",
+	"keywords": ["omp-plugin", "oh-my-pi", "omp", "tui", "claude-code"],
+	"files": ["index.ts", "src", "README.md", "LICENSE"],
+	"omp": {
+		"extensions": ["./index.ts"]
+	}
+}

package/src/render.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared Claude Code-style rendering primitives: `● Name(arg)` headers and the
+ * `⎿` result gutter.
+ */
+import os from "node:os";
+import { type Component, replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+import type { ToolRenderer } from "@oh-my-pi/pi-tui/tools";
+
+export type Theme = Parameters<ToolRenderer["renderCall"]>[2];
+export type RenderOptions = Parameters<ToolRenderer["renderResult"]>[1];
+export type RenderResult = Parameters<ToolRenderer["renderResult"]>[0];
+
+const FIRST_GUTTER = "  ⎿  ";
+const NEXT_GUTTER = "     ";
+
+/** Static styled lines truncated to the render width; same array while the width is unchanged. */
+export class Lines implements Component {
+	#lines: readonly string[];
+	#width = -1;
+	#cache: readonly string[] = [];
+
+	constructor(lines: readonly string[]) {
+		this.#lines = lines;
+	}
+
+	render(width: number): readonly string[] {
+		if (width !== this.#width) {
+			this.#width = width;
+			this.#cache = this.#lines.map(line => truncateToWidth(line, width));
+		}
+		return this.#cache;
+	}
+
+	invalidate(): void {
+		this.#width = -1;
+	}
+}
+
+export type CallState = "pending" | "running" | "success" | "error";
+
+/** Status bullet: blinking while running, dim while pending, green/red once settled. */
+export function bullet(theme: Theme, state: CallState, spinnerFrame?: number): string {
+	switch (state) {
+		case "success":
+			return theme.fg("success", "●");
+		case "error":
+			return theme.fg("error", "●");
+		case "running":
+			return spinnerFrame !== undefined && spinnerFrame % 2 === 1 ? " " : theme.fg("dim", "●");
+		default:
+			return theme.fg("dim", "●");
+	}
+}
+
+/** State of a settled-or-streaming result. */
+export function resultState(result: RenderResult, options: RenderOptions): CallState {
+	if (options.isPartial) return "running";
+	return result.isError ? "error" : "success";
+}
+
+/**
+ * State of a call that has no result yet. omp ticks the spinner while the call's
+ * arguments are still streaming, so only `executionStarted` means it is running.
+ */
+export function callState(options: RenderOptions): CallState {
+	return options.executionStarted ? "running" : "pending";
+}
+
+/** `● Name(arg)`; the parenthesised part is omitted when `arg` is undefined. */
+export function header(theme: Theme, state: CallState, name: string, arg?: string, spinnerFrame?: number): string {
+	const head = `${bullet(theme, state, spinnerFrame)} ${theme.bold(name)}`;
+	if (arg === undefined) return head;
+	return `${head}${theme.fg("muted", "(")}${replaceTabs(arg)}${theme.fg("muted", ")")}`;
+}
+
+export interface GutterOptions {
+	expanded: boolean;
+	/** Body rows shown while collapsed. */
+	limit: number;
+	/** Collapse to the last rows (streaming output) instead of the first. */
+	tail?: boolean;
+	/** Always shown before the body (a summary sentence); not counted against `limit`. */
+	lead?: readonly string[];
+	/** Always shown after the body (exit code, timeout); not counted against `limit`. */
+	trailer?: readonly string[];
+}
+
+/**
+ * Rows under the header behind the `⎿` gutter. Collapsed, only `limit` body rows
+ * show (the tail while streaming), with an expand hint for the rest; `lead` and
+ * `trailer` rows are never folded away.
+ */
+export function gutter(theme: Theme, rows: readonly string[], opts: GutterOptions): string[] {
+	let shown: string[] = rows.map(row => replaceTabs(row));
+	let hidden = 0;
+	if (!opts.expanded && shown.length > opts.limit) {
+		hidden = shown.length - opts.limit;
+		shown = opts.tail ? shown.slice(-opts.limit) : shown.slice(0, opts.limit);
+	}
+	if (hidden > 0) {
+		const hint = theme.fg("dim", `… +${hidden} line${hidden === 1 ? "" : "s"} (ctrl+o to expand)`);
+		if (opts.tail) shown.unshift(hint);
+		else shown.push(hint);
+	}
+	const all = [...(opts.lead ?? []).map(replaceTabs), ...shown, ...(opts.trailer ?? []).map(replaceTabs)];
+	return all.map((row, i) => (i === 0 ? FIRST_GUTTER : NEXT_GUTTER) + row);
+}
+
+/** Joined text content of a tool result, trailing whitespace removed. */
+export function resultText(result: RenderResult): string {
+	return result.content
+		.filter(block => block.type === "text" && typeof block.text === "string")
+		.map(block => block.text)
+		.join("\n")
+		.replace(/\s+$/, "");
+}
+
+/** Non-empty text as lines; empty text as no lines. */
+export function splitLines(text: string | undefined): string[] {
+	if (!text) return [];
+	return text.replace(/\s+$/, "").split("\n");
+}
+
+/** First line of a possibly multi-line value, marked with `…` when more follows. */
+export function firstLine(text: unknown): string {
+	if (typeof text !== "string") return "";
+	const lines = text.trim().split("\n");
+	return lines.length > 1 ? `${lines[0]} …` : (lines[0] ?? "");
+}
+
+/** macOS: `/tmp`, `/var`, `/etc` are symlinks into `/private`; paths may come either way. */
+function unprivate(p: string): string {
+	return p.replace(/^\/private(?=\/(?:tmp|var|etc)\/)/, "");
+}
+
+/** Display path: relative to the working directory, `~` for home, otherwise as given. */
+export function displayPath(value: unknown): string {
+	if (Array.isArray(value)) return value.map(displayPath).join(", ");
+	if (typeof value !== "string") return "";
+	const target = unprivate(value);
+	for (const dir of new Set([process.cwd(), process.env.PWD].filter(Boolean).map(d => unprivate(d!)))) {
+		if (target.startsWith(`${dir}/`)) return target.slice(dir.length + 1);
+	}
+	const home = os.homedir();
+	if (target.startsWith(`${home}/`)) return `~${target.slice(home.length)}`;
+	return value;
+}
+
+export function plural(count: number, noun: string, pluralNoun = `${noun}s`): string {
+	return `${count} ${count === 1 ? noun : pluralNoun}`;
+}