pi-umbra 0.1.0

package/node_modules/pi-umbra-theme/extensions/umbra-background.ts

@@ -0,0 +1,155 @@
+// pi picks a theme for its own text but never touches the window behind it. The only OSC 11 it
+// ever sends is the query form (`ESC ] 11 ; ? BEL`), so it reads your terminal background and
+// leaves it alone. A pi theme has no window-background token either: it paints the selected line,
+// the user message and the three tool boxes, nothing else.
+//
+// pi-omp-theme declares a `theme.terminalBackgroundSync` setting, but nothing in its source ever
+// reads that value and it never writes an OSC 11 set sequence. The knob does nothing.
+//
+// So this does it: on start it reads the active theme's own `export.pageBg` and sets the terminal
+// background to it, and on shutdown it puts the background back with OSC 111. Nothing is guessed —
+// a theme without an `export.pageBg` is left alone.
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const SETTINGS_KEY = "piUmbraTheme";
+// How often the active theme's name is compared. It is an in-memory string, so this costs a
+// comparison; the theme file is only read when the name moves. Short enough that arrowing through
+// the theme picker looks live.
+const POLL_MS = 250;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+
+// OSC 11 sets the default background; OSC 111 restores the one the terminal started with. BEL
+// terminates both, which every terminal accepts, unlike ST.
+const setBackground = (hex: string) => process.stdout.write(`\x1b]11;${hex}\x07`);
+const resetBackground = () => process.stdout.write("\x1b]111\x07");
+
+type Settings = { background?: string };
+
+const readSetting = (): string => {
+    const path = `${process.env.PI_AGENT_DIR ?? `${process.env.USERPROFILE ?? process.env.HOME}/.pi/agent`}/settings.json`;
+    try {
+        const settings = JSON.parse(readFileSync(path, "utf8")) as Record<string, Settings>;
+        return settings[SETTINGS_KEY]?.background ?? "auto";
+    } catch {
+        return "auto";
+    }
+};
+
+// The window colour a theme wants is its `export.pageBg` — the same value it uses for the page
+// behind an exported transcript. Render tokens are no help here; none of them is the window.
+// `ui.theme` is the loaded Theme. The file it was read from is only guaranteed on the list
+// `getAllThemes()` returns, and that list names the field `path`, not `sourcePath`. The instance is
+// tried first so a theme registered by another extension still resolves.
+const themeFile = (ctx: ExtensionContext): string | undefined => {
+    const theme = ctx.ui.theme;
+    if (theme === undefined) return undefined;
+    const own = (theme as { sourcePath?: string }).sourcePath;
+    if (own !== undefined) return own;
+    const listed = ctx.ui.getAllThemes().find((entry) => entry.name === theme.name);
+    return (listed as { path?: string } | undefined)?.path;
+};
+
+const themeBackground = (ctx: ExtensionContext): string | undefined => {
+    const path = themeFile(ctx);
+    if (path === undefined) return undefined;
+    const theme = JSON.parse(readFileSync(path, "utf8")) as { export?: { pageBg?: string } };
+    const pageBg = theme.export?.pageBg;
+    return pageBg !== undefined && HEX.test(pageBg) ? pageBg : undefined;
+};
+
+const resolve = (ctx: ExtensionContext): string | undefined => {
+    const setting = readSetting();
+    if (setting === "off") return undefined;
+    if (HEX.test(setting)) return setting;
+    return themeBackground(ctx);
+};
+
+export default function umbraBackground(pi: ExtensionAPI) {
+    // The colour currently on the terminal, or undefined when we have not touched it. One variable
+    // rather than a colour plus an "applied" flag: the two can disagree and the flag adds nothing.
+    let current: string | undefined;
+    // The theme name as of the last look, and the timer that does the looking.
+    let watched: string | undefined;
+    let watcher: ReturnType<typeof setInterval> | undefined;
+
+    const apply = (ctx: ExtensionContext): string | undefined => {
+        const hex = resolve(ctx);
+        if (hex === undefined) return undefined;
+        setBackground(hex);
+        current = hex;
+        return hex;
+    };
+
+    pi.on("session_start", (_event, ctx: ExtensionContext) => {
+        if (ctx.mode !== "tui") return;
+        apply(ctx);
+        // pi fires no theme-change event. Its internal onThemeChange slot holds a single callback
+        // that the TUI already owns, and ui_prompt_end does not cover pi's own theme picker, so the
+        // name is watched instead. unref keeps this timer from holding the process open at exit.
+        if (watcher !== undefined) clearInterval(watcher);
+        watched = ctx.ui.theme?.name;
+        watcher = setInterval(() => {
+            const name = ctx.ui.theme?.name;
+            if (name === watched) return;
+            watched = name;
+            apply(ctx);
+        }, POLL_MS);
+        watcher.unref?.();
+    });
+
+    // Leaving a recoloured terminal behind is the one unfriendly thing this could do, so undo it
+    // whether or not the shell would have reset it.
+    pi.on("session_shutdown", () => {
+        if (watcher !== undefined) clearInterval(watcher);
+        watcher = undefined;
+        if (current === undefined) return;
+        resetBackground();
+        current = undefined;
+    });
+
+    // Two arguments, not one object: pi's signature is registerCommand(name, definition), and a
+    // single object lands in the `name` slot, where the autocomplete filter calls toLowerCase on
+    // it and takes the whole process down the first time anyone types "/".
+    pi.registerCommand("umb-bg", {
+        description: "Set the terminal background from the active theme, a hex colour, or reset it",
+        handler: async (args: string, ctx: ExtensionContext) => {
+            if (ctx.mode !== "tui") return;
+            const argument = args.trim();
+
+            if (argument === "off" || argument === "reset") {
+                resetBackground();
+                current = undefined;
+                ctx.ui.notify("Terminal background restored.", "info");
+                return;
+            }
+
+            if (HEX.test(argument)) {
+                setBackground(argument);
+                current = argument;
+                ctx.ui.notify(`Terminal background set to ${argument}.`, "info");
+                return;
+            }
+
+            if (argument !== "") {
+                ctx.ui.notify(`Expected a #rrggbb colour, "off", or nothing. Got "${argument}".`, "error");
+                return;
+            }
+
+            // Three outcomes, three messages. "Nothing happened" is useless when the cause can be
+            // the theme having no colour, pi not listing the theme's file, or the terminal
+            // dropping the escape - and only the last one is out of this extension's hands.
+            const name = ctx.ui.theme?.name ?? "?";
+            const file = themeFile(ctx);
+            const hex = apply(ctx);
+            ctx.ui.notify(
+                hex !== undefined
+                    ? `Terminal background set to ${hex} from theme "${name}". If it did not change, this terminal ignores OSC 11.`
+                    : file === undefined
+                      ? `pi lists no file for theme "${name}", so its background cannot be read. Use /umb-bg #rrggbb.`
+                      : `Theme "${name}" (${file}) defines no export.pageBg, so nothing was changed.`,
+                hex === undefined ? "warning" : "info",
+            );
+        },
+    });
+}

package/node_modules/pi-umbra-theme/extensions/umbra-footer.ts

@@ -0,0 +1,150 @@
+import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { compact } from "../lib/umbra-format.ts";
+
+const ANSI_CODES = /\x1b\[[0-9;]*m/g;
+
+const ponytailLevel = (statuses: ReadonlyMap<string, string>) => {
+	const status = statuses.get("ponytail")?.replace(ANSI_CODES, "").toLowerCase() ?? "";
+	return status.match(/lite|full|ultra/)?.[0];
+};
+
+// One column in on the left, the same gutter bar/bar-line.ts uses, so the footer and the agent
+// rows under it start on the same column. Two on the right, matching the input bar: the right
+// edge is where a long path ends, and one column there reads as the text touching the border.
+const PAD_LEFT = 1;
+const PAD_RIGHT = 2;
+
+// Two columns on one row, with the gap doing the alignment. A terminal too narrow to hold both
+// drops the right column whole rather than truncating a path into something unreadable — the
+// left column is the one that changes every turn, so it is the one worth keeping.
+const SEP = " · ";
+
+/** As many groups per line as fit, in order. A group too wide for a line of its own is cut. */
+const pack = (groups: string[], inner: number): string[] => {
+	const lines: string[] = [];
+	let line = "";
+	for (const group of groups) {
+		if (line === "") line = truncateToWidth(group, inner);
+		else if (visibleWidth(line) + SEP.length + visibleWidth(group) <= inner) line += SEP + group;
+		else {
+			lines.push(line);
+			line = truncateToWidth(group, inner);
+		}
+	}
+	if (line !== "") lines.push(line);
+	return lines;
+};
+
+/**
+ * The status groups over as many rows as they need, and the path on the last one when it fits.
+ * Truncating instead would drop whichever group came last - and the groups are ordered by how
+ * often they are read, so the cut always landed on the ones nobody had seen yet.
+ *
+ * Packed while plain: colour is applied per finished line, so an escape is never cut in half and
+ * visibleWidth is measuring characters rather than ANSI.
+ */
+const compose = (left: string[], right: string[], width: number, paint: (t: string) => string): string[] => {
+	const inner = Math.max(0, width - PAD_LEFT - PAD_RIGHT);
+	const pad = (line: string) => " ".repeat(PAD_LEFT) + paint(line) + " ".repeat(PAD_RIGHT);
+	const lines = pack(left, inner);
+	const tail = right.join(SEP);
+	if (tail === "") return lines.map(pad);
+
+	const last = lines.pop() ?? "";
+	const gap = inner - visibleWidth(last) - visibleWidth(tail);
+	if (gap >= 2) lines.push(last + " ".repeat(gap) + tail);
+	else lines.push(last, truncateToWidth(tail, inner));
+	return lines.map(pad);
+};
+
+export default function (pi: ExtensionAPI) {
+	// Computed once per turn and read on every frame, rather than the other way round.
+	// getBranch() is documented as a tree traversal from the current leaf and builds a fresh
+	// array each call, so scanning the whole session inside render() re-walked it on every
+	// paint — dozens of times a second while a reply streams, and O(session) each time.
+	let cost = 0;
+	let lastTurn: Usage | undefined;
+	let repaint: (() => void) | undefined;
+
+	const refresh = (ctx: ExtensionContext) => {
+		const messages = ctx.sessionManager
+			.getBranch()
+			.filter((entry) => entry.type === "message" && entry.message.role === "assistant")
+			.map((entry) => (entry as { message: AssistantMessage }).message);
+		// On a subscription this is not what was billed — it is what the provider priced the
+		// turns at, and only a provider that reports per-turn cost fills it in at all.
+		cost = messages.reduce((sum, message) => sum + message.usage.cost.total, 0);
+		lastTurn = messages.at(-1)?.usage;
+		repaint?.();
+	};
+
+	// agent_end, not message_end. core/cache-stats.d.ts:46 states that message_end fires BEFORE
+	// persistence, so getBranch() there would still be missing the turn that just finished and
+	// the footer would report the previous one. agent_end runs after every message_end, and that
+	// gap is where the numbers were arriving a frame late: nothing asked for a repaint once the
+	// entry landed, so new usage waited for whatever redrew the screen next — usually a keystroke.
+	pi.on("agent_end", (_event, ctx) => refresh(ctx));
+
+	pi.on("session_start", async (_event, ctx) => {
+		// A resumed session already has turns behind it, and no agent_end will fire for them.
+		refresh(ctx);
+		ctx.ui.setFooter((tui, theme, footerData) => {
+			repaint = () => tui.requestRender();
+			return {
+				dispose: footerData.onBranchChange(() => tui.requestRender()),
+				invalidate() {},
+				render(width: number) {
+					const promptTokens =
+						(lastTurn?.input ?? 0) + (lastTurn?.cacheRead ?? 0) + (lastTurn?.cacheWrite ?? 0);
+					const cacheHitRate = promptTokens > 0 ? ((lastTurn?.cacheRead ?? 0) / promptTokens) * 100 : 0;
+					const context = ctx.getContextUsage();
+
+					// "MiniMax: MiniMax M3 (CC)" → "MiniMax M3". pi names a model "<provider>: <model>"
+					// and the provider is already implied by the model, so both the prefix and the
+					// trailing parenthetical are noise on a line this crowded.
+					const modelName = (ctx.model?.name ?? "no model")
+						.replace(/^[^:]*:\s*/, "")
+						.replace(/\s*\([^)]*\)$/, "");
+					const parts = [
+						`${modelName} [${ctx.thinkingLevel}]`,
+						`${compact(context?.tokens ?? 0)}/${compact(context?.contextWindow ?? 0)}`,
+					];
+					// A free model prices every turn at zero, and a column that only ever reads $0.00
+					// is a column that teaches you to stop looking at it. Each group below appears
+					// once it has something to say and takes its space back when it does not.
+					if (cost > 0) parts.push(`$${cost.toFixed(2)}`);
+					const cached = (lastTurn?.cacheRead ?? 0) + (lastTurn?.cacheWrite ?? 0);
+					if (cached > 0) {
+						parts.push(
+							`R${compact(lastTurn?.cacheRead ?? 0)} W${compact(lastTurn?.cacheWrite ?? 0)} CH${cacheHitRate.toFixed(1)}%`,
+						);
+					}
+					// `input` is the fresh half of the prompt. cacheRead and cacheWrite are already
+					// their own group, so counting them here too would make the arrow repeat what the
+					// R and the W just said.
+					const moved = (lastTurn?.input ?? 0) + (lastTurn?.output ?? 0);
+					if (moved > 0) parts.push(`↑ ${compact(lastTurn?.input ?? 0)} ↓ ${compact(lastTurn?.output ?? 0)}`);
+					const statuses = footerData.getExtensionStatuses();
+					const level = ponytailLevel(statuses);
+					if (level) parts.push(`ponytail:${level}`);
+					const loop = statuses.get("loop")?.replace(ANSI_CODES, "");
+					if (loop) parts.push(loop);
+
+					// getGitBranch() returns null outside a repo and "detached" on a detached HEAD, so
+					// the branch shows itself when there is one and costs nothing when there is not.
+					const right = [`🗀  ${ctx.sessionManager.getCwd()}`];
+					const branch = footerData.getGitBranch();
+					if (branch) right.push(`⎇ ${branch}`);
+
+					// One line. The rule that used to live here is drawn by the editor now - see the
+					// repatch entry "the autocomplete list has a closing edge" - which puts it in the
+					// border colour and only when there is a list to close. Drawing it here as well
+					// showed up as two rules with a blank row between them on every screen with no list.
+					return compose(parts, right, width, (text) => theme.fg("muted", text));
+				},
+			};
+		});
+	});
+}

package/node_modules/pi-umbra-theme/extensions/umbra-gutter.ts

@@ -0,0 +1,35 @@
+// Model text and your own text run into each other in a long session. This puts a gutter beside
+// everything the model says, so the two are separable at a glance.
+//
+// It is drawn as a Markdown quote rather than a literal "│ " prefix, because the transformer hook
+// is display-only and operates on Markdown source: a literal prefix would turn "```ts" into
+// "│ ```ts", which is no longer a fence, and every code block in the answer would render as
+// paragraph text. A quote keeps fences, lists and tables intact, and pi's own renderer draws the
+// bar from the active theme.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readUmbraSettings } from "../lib/umbra-settings.ts";
+
+const QUOTE = "> ";
+
+/**
+ * A blank line inside a quote ends it, so blank lines carry a bare marker. Without that, one
+ * empty line between two paragraphs would split the answer into two separate quote blocks.
+ */
+export const asQuote = (markdown: string): string =>
+    markdown
+        .split("\n")
+        .map((line) => (line.trim() === "" ? QUOTE.trimEnd() : QUOTE + line))
+        .join("\n");
+
+export default function umbraGutter(pi: ExtensionAPI) {
+    // Read once. The transformer runs on every streaming update and every terminal resize, so a
+    // file read per call would put disk I/O on the render path.
+    const isGutterEnabled = readUmbraSettings().messages?.assistantPrefix === true;
+    if (!isGutterEnabled) return;
+
+    pi.registerMarkdownTransformer((markdown: string, { messageType }: { messageType: string }) => {
+        if (messageType !== "assistant") return markdown;
+        if (markdown.trim() === "") return markdown;
+        return asQuote(markdown);
+    });
+}

package/node_modules/pi-umbra-theme/extensions/umbra-toolbox.ts

@@ -0,0 +1,129 @@
+// Draws a frame around every tool call, so a long transcript reads as blocks instead of one
+// stream. pi paints a background behind tool output but no border, and there is no public hook
+// for the frame: a tool's own `renderCall`/`renderResult` only cover that one tool, and most
+// tools are pi's own.
+//
+// So this patches `ToolExecutionComponent.prototype.render`, which is the safest joint available:
+//
+//   - The class is exported from `@earendil-works/pi-coding-agent`, not reached out of a private
+//     module, so pi means for extensions to hold it.
+//   - `render(width): string[]` is the `Component` contract every pi component implements, so it
+//     is the least likely method on the class to change shape.
+//   - The patch is purely additive. It reads pi's finished lines and returns them with a border
+//     around them. It never reproduces what pi drew, so syntax highlighting, diffs, images and
+//     the expand affordance all keep working untouched.
+//
+// It is still a patch, and a pi upgrade can still invalidate it. Two guards make that harmless:
+// the shape of `render` is verified before anything is replaced, and any throw inside the frame
+// returns pi's own lines. The failure mode is "the frames disappear", never "the session breaks".
+import { type Theme, ToolExecutionComponent } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readUmbraSettings } from "../lib/umbra-settings.ts";
+
+const TOP_LEFT = "╭";
+const TOP_RIGHT = "╮";
+const BOTTOM_LEFT = "╰";
+const BOTTOM_RIGHT = "╯";
+const HORIZONTAL = "─";
+const VERTICAL = "│";
+
+/** A border plus one space of padding on each side. */
+const FRAME_COLUMNS = 4;
+/** Below this there is no room for content between the two verticals. */
+const MIN_WIDTH = 12;
+
+// The scrollbar owns the last column of the chat, and a frame drawn out to the full width puts
+// its right border directly against it. One column short of the edge is what separates them.
+export const RIGHT_MARGIN = 1;
+
+/** pi's own `render` takes the available width and returns the drawn lines. */
+const RENDER_ARITY = 1;
+
+type Render = (width: number) => string[];
+
+/**
+ * The lines carry ANSI colour, so their length in characters is not their width on screen.
+ * `visibleWidth` is pi's own measurement and is what the frame has to line up against.
+ */
+const padToWidth = (line: string, columns: number): string => {
+    const missing = columns - visibleWidth(line);
+    return missing > 0 ? line + " ".repeat(missing) : line;
+};
+
+/**
+ * pi's tool component opens with a blank spacer line. Framing that would put an empty row inside
+ * the box, so leading and trailing blanks are lifted out and re-emitted around the frame.
+ */
+const splitBlanks = (lines: string[]): { before: string[]; body: string[]; after: string[] } => {
+    let first = 0;
+    let last = lines.length;
+    while (first < last && lines[first]?.trim() === "") first++;
+    while (last > first && lines[last - 1]?.trim() === "") last--;
+    return { before: lines.slice(0, first), body: lines.slice(first, last), after: lines.slice(last) };
+};
+
+/** The width the frame itself is drawn at: everything but the column the scrollbar sits in. */
+export const framedWidth = (width: number): number => Math.max(0, width - RIGHT_MARGIN);
+
+/** What pi may draw into, once the border, its padding and that margin have taken their columns. */
+export const usableWidth = (width: number): number =>
+    framedWidth(width) < MIN_WIDTH ? width : framedWidth(width) - FRAME_COLUMNS;
+
+export const frame = (lines: string[], width: number, paint: (text: string) => string): string[] => {
+    if (width < MIN_WIDTH) return lines;
+    const { before, body, after } = splitBlanks(lines);
+    if (body.length === 0) return lines;
+
+    const inner = width - FRAME_COLUMNS;
+    const rule = HORIZONTAL.repeat(width - 2);
+    const side = paint(VERTICAL);
+    return [
+        ...before,
+        paint(TOP_LEFT + rule + TOP_RIGHT),
+        ...body.map((line) => `${side} ${padToWidth(line, inner)} ${side}`),
+        paint(BOTTOM_LEFT + rule + BOTTOM_RIGHT),
+        ...after,
+    ];
+};
+
+/**
+ * Refuse to patch a method that is not the one this was written against. An upgrade that changes
+ * `render` leaves pi drawing its own rows, which is a worse look and a working session.
+ */
+const isPatchable = (): boolean => {
+    const render: unknown = ToolExecutionComponent?.prototype?.render;
+    return typeof render === "function" && (render as Render).length === RENDER_ARITY;
+};
+
+export default function umbraToolbox(pi: ExtensionAPI) {
+    if (readUmbraSettings().tools?.chrome !== "boxed") return;
+    if (!isPatchable()) return;
+
+    pi.on("session_start", (_event, ctx: ExtensionContext) => {
+        if (ctx.mode !== "tui") return;
+
+        const prototype = ToolExecutionComponent.prototype;
+        // SAFETY: isPatchable() checked above that this is a one-argument function, which is the
+        // whole contract the wrapper depends on.
+        const original = prototype.render as Render;
+        if ((prototype.render as { umbra?: boolean }).umbra === true) return;
+
+        const paint = (text: string) => (ctx.ui.theme as Theme | undefined)?.fg("borderMuted", text) ?? text;
+
+        const patched: Render & { umbra?: boolean } = function (this: unknown, width: number) {
+            // pi is asked for the inner width, not the full one. Rendering at `width` and then
+            // putting a border around it pushes every full-width line four columns past the right
+            // edge, which is what made long tool output break out of the box.
+            const lines = original.call(this, usableWidth(width));
+            if (lines.length === 0) return lines;
+            try {
+                return frame(lines, framedWidth(width), paint);
+            } catch {
+                return lines;
+            }
+        };
+        patched.umbra = true;
+        prototype.render = patched;
+    });
+}