one-code-extension 0.1.4 → 0.3.0

package/extensions/lib/tui-render.ts

@@ -15,7 +15,10 @@
  * every line goes through `truncateLine` — never skip it.
  */
 
-import { NOTIFICATION_HEADER, NOTIFICATION_PREFIX } from "./notifications.ts";
+import { notificationBody } from "./notifications.ts";
+import { fitPainted, hardWrapColumns, sliceColumns, visibleWidth } from "./text-width.ts";
+export { notificationBody };
+export { visibleWidth } from "./text-width.ts";
 
 /** The structural subset of pi-tui's Component that pi's renderers require. */
 export interface TuiComponent {
@@ -30,6 +33,22 @@ export interface ThemeLike {
 	italic(text: string): string;
 }
 
+/**
+ * A ctx that is live and has a UI, else undefined. pi invalidates an
+ * extension's ctx when the session is replaced (/clear, /new, /resume —
+ * findings §8): every getter on it throws from then on, and a widget's timer or
+ * a child's late event can still fire afterwards. Painting through this turns
+ * the stale ctx into "no UI" instead of an uncaught throw in a timer callback,
+ * which took the whole process down once (SUBAGENT-REVIEW H1).
+ */
+export function liveUiCtx<T extends { hasUI: boolean }>(ctx: T | undefined): T | undefined {
+	try {
+		return ctx?.hasUI ? ctx : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /**
  * A `paint(color, text)` closure that degrades to the plain text whenever the
  * theme is missing, lacks `fg`, or `fg` throws — the guard every `ctx.ui.custom`
@@ -46,49 +65,208 @@ export function safeThemePaint(theme: unknown): (color: string, text: string) =>
 	};
 }
 
+/** The `inverse(text)` counterpart to safeThemePaint, with the same degrade-to-plain guard. */
+export function safeThemeInverse(theme: unknown): (text: string) => string {
+	return (text: string) => {
+		const themed = theme as { inverse?(t: string): string } | undefined;
+		try {
+			return themed?.inverse ? themed.inverse(text) : text;
+		} catch {
+			return text;
+		}
+	};
+}
+
+/** The `bold(text)` counterpart to safeThemePaint, with the same degrade-to-plain guard. */
+export function safeThemeBold(theme: unknown): (text: string) => string {
+	return (text: string) => {
+		const themed = theme as { bold?(t: string): string } | undefined;
+		try {
+			return themed?.bold ? themed.bold(text) : text;
+		} catch {
+			return text;
+		}
+	};
+}
+
+/** Humane elapsed time, Claude Code style: 45s, 1m 7s, 2h 5m. */
+export function formatDuration(startedAt?: number, finishedAt?: number, now?: number): string {
+	if (startedAt === undefined) return "";
+	const end = finishedAt ?? now ?? startedAt;
+	const total = Math.max(0, Math.round((end - startedAt) / 1000));
+	if (total < 60) return `${total}s`;
+	if (total < 3600) return `${Math.floor(total / 60)}m ${total % 60}s`;
+	return `${Math.floor(total / 3600)}h ${Math.floor((total % 3600) / 60)}m`;
+}
+
+/** `2 shells`, `1 shell` — a count with its (s-pluralized) noun. */
+export function countNoun(count: number, noun: string): string {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** Right-align plain text within `width` terminal columns. */
+export function alignRight(text: string, width: number): string {
+	const length = visibleWidth(text);
+	if (length >= width) return sliceColumns(text, Math.max(0, width)).text;
+	return " ".repeat(width - length) + text;
+}
+
 /**
- * Cut a painted line to `width` visible columns without splitting ANSI escape
- * sequences, ending with an ellipsis and a reset so truncation cannot leak a
- * colour into the next line. pi-tui *crashes* the whole app on an overwide
- * line ("Rendered line exceeds terminal width"), and only validates a
- * component when its output changes — so an overflow can hide in static
- * content for weeks, then kill pi the moment something makes it re-render.
+ * setWidget factory for a one-line, dim, right-aligned note (Claude Code's
+ * above-input chrome: the context token counter, the effort-changed note).
+ * The one-column right margin matches the paddingX pi gives string widgets.
  */
-const ANSI_AT = /\x1b\[[0-9;]*m/y;
+export function dimRightAlignedWidget(text: string): (tui: unknown, theme: unknown) => TuiComponent {
+	return (_tui, theme) => {
+		const paint = safeThemePaint(theme);
+		return linesComponent((width) => [paint("dim", alignRight(text, Math.max(1, width - 1)))]);
+	};
+}
 
-export function truncateLine(line: string, width: number): string {
+/** Strikethrough via raw SGR 9/29 — pi themes have no strike paint. */
+export function strike(text: string): string {
+	return `\x1b[9m${text}\x1b[29m`;
+}
+
+/**
+ * Height for a bounded panel that docks below the transcript (like Claude
+ * Code's /plugins and /skills): capped at `max` so the conversation stays
+ * visible, at least `min` when the terminal has room — but never taller than
+ * the terminal itself, so a short pane (< min+2 rows) shrinks to fit instead of
+ * overflowing.
+ */
+export function boundedDockHeight(terminalRows: number, max: number, min = 12): number {
+	const avail = Math.max(1, terminalRows - 2);
+	return avail <= min ? avail : Math.min(avail, max);
+}
+
+/** Cut plain (unpainted) text to `width` terminal columns, with an ellipsis. */
+export function cutPlainText(text: string, width: number): string {
 	if (width <= 0) return "";
-	// Raw length bounds visible width (escapes only ever add), so a line whose
-	// raw length fits needs no scan — the hot path for nearly every line.
-	if (line.length <= width) return line;
-	let visible = 0;
-	for (let i = 0; i < line.length; ) {
-		ANSI_AT.lastIndex = i;
-		const escape = ANSI_AT.exec(line);
-		if (escape) {
-			i += escape[0].length;
-			continue;
-		}
-		visible++;
-		i++;
+	if (visibleWidth(text) <= width) return text;
+	// Reserve one column for the ellipsis (itself width 1).
+	return `${sliceColumns(text, Math.max(0, width - 1)).text}…`;
+}
+
+/** Cut then pad plain (unpainted) text to exactly `width` terminal columns. */
+export function padPlainText(text: string, width: number): string {
+	const shortened = cutPlainText(text, width);
+	return shortened + " ".repeat(Math.max(0, width - visibleWidth(shortened)));
+}
+
+/** First non-empty line of a possibly-multiline string, trimmed. */
+export function firstNonEmptyLine(text: string): string {
+	return text.split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+}
+
+/**
+ * Full-width rule that separates a docked panel from the transcript above it,
+ * the way Claude Code frames its /skills, /plugins and /mcp menus. Paint takes
+ * a (color, text) painter; the "border" theme token gives a visible-but-calm line.
+ */
+export function panelTopRule(paint: (color: string, text: string) => string, width: number): string {
+	return paint("border", "─".repeat(Math.max(0, width)));
+}
+
+/**
+ * A rounded, bordered single-line search input, Claude Code style. Returns three
+ * lines (top border, the input row, bottom border), already indented one column.
+ * The placeholder shows dim until the user types. `paint` colors the border with
+ * the "border" token; the query text stays in the default foreground.
+ */
+export function searchBoxLines(
+	query: string,
+	placeholder: string,
+	paint: (color: string, text: string) => string,
+	width: number,
+): string[] {
+	const boxWidth = Math.max(12, width - 2); // one column of margin each side
+	const inner = boxWidth - 2; // space between the vertical borders
+	const label = query ? `⌕ ${query}` : `⌕ ${placeholder}`;
+	const cut = cutPlainText(label, inner - 2); // one space padding each side
+	const content = ` ${cut}${" ".repeat(Math.max(0, inner - 2 - visibleWidth(cut)))} `;
+	const v = paint("border", "│");
+	return [
+		` ${paint("border", `╭${"─".repeat(inner)}╮`)}`,
+		` ${v}${query ? content : paint("dim", content)}${v}`,
+		` ${paint("border", `╰${"─".repeat(inner)}╯`)}`,
+	];
+}
+
+/** A run of rendered lines that either can (`selectable`) or cannot host the cursor. */
+export interface RenderBlock {
+	lines: string[];
+	selectable: boolean;
+}
+
+/**
+ * Window a list of blocks so the block holding the Nth selectable row (`cursor`)
+ * stays visible within `budget` lines, returning the visible lines and how many
+ * blocks fell off the bottom. Group headers ride along as non-selectable blocks.
+ * The cursor's own block is always shown even when it alone exceeds the budget,
+ * so a tall selected row never scrolls itself off screen.
+ */
+export function windowBlocks(blocks: RenderBlock[], cursor: number, budget: number): { lines: string[]; more: number } {
+	const selectableIndexes = blocks.map((b, i) => (b.selectable ? i : -1)).filter((i) => i >= 0);
+	const cursorBlock = selectableIndexes[cursor] ?? 0;
+	const linesBetween = (from: number, to: number) => blocks.slice(from, to + 1).reduce((n, b) => n + b.lines.length, 0);
+	let start = 0;
+	while (start < cursorBlock && linesBetween(start, cursorBlock) > budget) start++;
+	const lines: string[] = [];
+	let index = start;
+	for (; index < blocks.length; index++) {
+		if (lines.length > 0 && lines.length + blocks[index].lines.length > budget) break;
+		lines.push(...blocks[index].lines);
 	}
-	if (visible <= width) return line;
-
-	let out = "";
-	let used = 0;
-	for (let i = 0; i < line.length && used < width - 1; ) {
-		ANSI_AT.lastIndex = i;
-		const escape = ANSI_AT.exec(line);
-		if (escape) {
-			out += escape[0];
-			i += escape[0].length;
-			continue;
-		}
-		out += line[i];
-		used++;
-		i++;
+	return { lines, more: blocks.length - index };
+}
+
+/**
+ * Split a row into a left half padded against a right-aligned annotation
+ * (two-space gap), fusing into one cut line when the left share would drop
+ * below readability. The single home of this layout rule — strip rows, pane
+ * rows, and transcript headers all build on it.
+ */
+export function splitRow(left: string, right: string, width: number): { fused: string } | { left: string; right: string } {
+	const rightWidth = visibleWidth(right);
+	const leftWidth = width - rightWidth - 2;
+	if (rightWidth === 0 || leftWidth < 8) return { fused: cutPlainText(`${left}  ${right}`.trimEnd(), width) };
+	return { left: padPlainText(left, leftWidth), right };
+}
+
+/** splitRow flattened to one plain string, exactly `width` wide. */
+export function splitCell(left: string, right: string, width: number): string {
+	const row = splitRow(left, right, width);
+	return "fused" in row ? padPlainText(row.fused, width) : `${row.left}  ${row.right}`;
+}
+
+/** Hard-wrap plain text to `width` terminal columns, preserving blank lines. */
+export function wrapPlainText(text: string, width: number): string[] {
+	const columns = Math.max(1, width);
+	const out: string[] = [];
+	for (const raw of text.replace(/\r\n/g, "\n").split("\n")) {
+		if (raw.length === 0) out.push("");
+		else out.push(...hardWrapColumns(raw, columns));
 	}
-	return `${out}\x1b[0m…`;
+	return out;
+}
+
+/**
+ * Cut a painted line to `width` terminal columns without splitting ANSI escape
+ * sequences or a wide/emoji grapheme, ending with an ellipsis and a reset so
+ * truncation cannot leak a colour into the next line. pi-tui *crashes* the
+ * whole app on an overwide line ("Rendered line exceeds terminal width") — and
+ * it measures columns, not code points: a CJK ideograph or an emoji is two
+ * columns wide (findings/TUI-REVIEW H1). It only validates a component when its
+ * output changes, so an overflow can hide in static content for weeks, then
+ * kill pi the moment something makes it re-render.
+ */
+export function truncateLine(line: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(line) <= width) return line;
+	// Reserve one column for the ellipsis (itself width 1).
+	const { text } = fitPainted(line, Math.max(0, width - 1));
+	return `${text}\x1b[0m…`;
 }
 
 /**
@@ -117,6 +295,16 @@ export function linesComponent(build: (width: number) => string[]): TuiComponent
 	};
 }
 
+/**
+ * A single dim transcript line led by a dim mark ("✻ Cooked for 5m 12s",
+ * "※ recap: …") — the shared shape behind the turn-duration and recap
+ * display-only entries. Width-memoized via linesComponent.
+ */
+export function dimMarkedLine(theme: unknown, mark: string, text: string): TuiComponent {
+	const paint = safeThemePaint(theme);
+	return linesComponent(() => [`${paint("dim", mark)} ${paint("dim", text)}`]);
+}
+
 /**
  * Params commonly carrying the human-meaningful part of a tool call, in
  * priority order. Used when a tool does not supply its own `title`.
@@ -342,27 +530,13 @@ export function ccToolRenderers<TArgs = any, TDetails = any>(
 			} catch {
 				text = undefined;
 			}
-			text ??= textContent(result);
+			text ??= textContent(stripReminderBlocks(result));
 			if (!text) return linesComponent(() => []);
 			return linesComponent(() => resultLines(theme, text, options.expanded, context.isError, spec.maxCollapsedLines));
 		},
 	};
 }
 
-/**
- * Strip the `systemNotification` anti-confabulation framing for display: the
- * framing exists for the model, not the user (findings §14). Returns the body.
- */
-export function notificationBody(text: string): string {
-	const lines = text.split("\n");
-	if (lines[0]?.startsWith(NOTIFICATION_HEADER)) {
-		let i = 1;
-		while (i < lines.length && (lines[i].trim() === "" || lines[i].startsWith(NOTIFICATION_PREFIX))) i++;
-		return lines.slice(i).join("\n").trim();
-	}
-	return text.trim();
-}
-
 /** True when a line is visually empty — ANSI codes (Box padding paints) don't count as content. */
 export function isBlankLine(line: string): boolean {
 	return line.replace(/\x1b\[[0-9;]*m/g, "").trim() === "";
@@ -394,6 +568,58 @@ export interface CcWrapOptions<TArgs = any> {
  * because base renderers cast `lastComponent` to their own concrete classes
  * and would throw on our wrapper.
  */
+/**
+ * One harness block as it is written into a stored tool result: the
+ * `<system-reminder>` frame, the raw `<total_tokens>` budget line, the raw
+ * `<new-diagnostics>` block. Model-facing only; every transcript view strips
+ * them (Claude Code shows none of these to the user).
+ */
+const HARNESS_BLOCK = String.raw`<system-reminder>[\s\S]*?</system-reminder>|<total_tokens>[^<]*</total_tokens>|<new-diagnostics>[\s\S]*?</new-diagnostics>`;
+/** A text block that IS a harness block (the injector appends them as blocks of their own). */
+const HARNESS_BLOCK_ONLY = new RegExp(String.raw`^\s*(?:${HARNESS_BLOCK})\s*$`);
+/** A run of harness blocks at the END of a text block (the same bytes after a merge or a `suffix`). */
+const HARNESS_TAIL = new RegExp(String.raw`(?:\s*(?:${HARNESS_BLOCK}))+\s*$`);
+
+/**
+ * Display text with the harness blocks that were appended to it removed. Only
+ * a block that stands alone or closes the text is stripped — never one quoted
+ * in the middle of real output (a file that documents these tags reads back
+ * intact). Returns "" when nothing but harness blocks remained.
+ */
+export function stripHarnessText(text: string): string {
+	if (HARNESS_BLOCK_ONLY.test(text)) return "";
+	return text.replace(HARNESS_TAIL, "");
+}
+
+/**
+ * A tool result with the harness blocks removed from its content, for display.
+ * One-shot reminders are persisted into the stored result (system-reminder
+ * extension) as text blocks of their own; the model must see them, the
+ * transcript view must not — Claude Code hides them the same way. A text block
+ * that ends in harness blocks keeps its own text and loses the tail.
+ */
+export function stripReminderBlocks<T extends { content?: unknown }>(result: T): T {
+	const content = result?.content;
+	if (!Array.isArray(content)) return result;
+	let changed = false;
+	const kept: unknown[] = [];
+	for (const block of content) {
+		const text = block && typeof block === "object" && (block as any).type === "text" ? (block as any).text : undefined;
+		if (typeof text !== "string") {
+			kept.push(block);
+			continue;
+		}
+		const stripped = stripHarnessText(text);
+		if (stripped === text) {
+			kept.push(block);
+			continue;
+		}
+		changed = true;
+		if (stripped !== "") kept.push({ ...(block as object), text: stripped });
+	}
+	return changed ? { ...result, content: kept } : result;
+}
+
 export function ccWrapBuiltinRenderers<TArgs = any>(
 	label: string,
 	base: {
@@ -455,7 +681,8 @@ export function ccWrapBuiltinRenderers<TArgs = any>(
 				},
 			};
 		},
-		renderResult(result: any, options: { expanded: boolean; isPartial: boolean }, theme: ThemeLike, context: any) {
+		renderResult(rawResult: any, options: { expanded: boolean; isPartial: boolean }, theme: ThemeLike, context: any) {
+			const result = stripReminderBlocks(rawResult);
 			let inner: any;
 			try {
 				inner = base.renderResult?.(result, options, theme, { ...context, lastComponent: context.state.ccInnerResult });

package/extensions/lib/usage-bus.ts

@@ -0,0 +1,75 @@
+/**
+ * Cross-extension usage bus. pi's built-in footer only sums the MAIN session's
+ * entries (assistant messages, tool-result/summary usage) — it never sees the
+ * LLM calls our other extensions make out-of-band: in-process subagents run in
+ * their own sessions, and the auto-mode classifier and web-fetch reader are
+ * one-shot `completeSimple` calls with no session at all. Our footer wants a
+ * true all-in cost, so each of those call sites reports its usage here and the
+ * footer accumulates it on top of the main-session total.
+ *
+ * The channel carries a small pre-extracted record rather than a raw pi-ai
+ * `Usage`, so no consumer has to know the provider's shape. `recordUsage`
+ * swallows its own errors — accounting must never break a tool path.
+ */
+
+export const USAGE_CHANNEL = "one-code:usage-recorded";
+
+/**
+ * Session entry type each record is persisted under (`pi.appendEntry`), so the
+ * all-in cost survives `--continue`/`--session` and a footer that mounts late
+ * (the bus is live-only; the entries are the durable ledger the footer sums).
+ * Custom entries never enter the LLM context.
+ */
+export const USAGE_ENTRY_TYPE = "one-code:usage";
+
+export type UsageSource = "subagent" | "classifier" | "reader" | "recap" | "setup";
+
+export interface UsageRecord {
+	source: UsageSource;
+	/** Dollar cost of the call (pi-ai `Usage.cost.total`), 0 when unpriced. */
+	cost: number;
+}
+
+/** Safe `cost.total` from an untrusted usage-like object. */
+export function costOf(usage: unknown): number {
+	if (!usage || typeof usage !== "object") return 0;
+	const cost = (usage as { cost?: { total?: unknown } }).cost;
+	const total = cost?.total;
+	return typeof total === "number" && Number.isFinite(total) ? total : 0;
+}
+
+/**
+ * Minimal shape we need off the extension API: the event emitter, plus the
+ * entry appender when the caller has one (unit tests may pass a bare emitter).
+ */
+type EventEmitter = {
+	events: { emit(channel: string, data: unknown): void };
+	appendEntry?<T>(customType: string, data?: T): void;
+};
+
+/**
+ * Report one non-main LLM call's usage: persisted as a session entry (the
+ * durable ledger) and announced on the bus (the live repaint signal). A no-op
+ * when the call was unpriced (the footer only sums cost), and never throws
+ * into the caller.
+ */
+export function recordUsage(pi: EventEmitter, source: UsageSource, usage: unknown): void {
+	try {
+		const cost = costOf(usage);
+		if (cost === 0) return;
+		const record: UsageRecord = { source, cost };
+		pi.appendEntry?.(USAGE_ENTRY_TYPE, record);
+		pi.events.emit(USAGE_CHANNEL, record);
+	} catch {
+		// Accounting is best-effort; a broken emit must not fail the tool.
+	}
+}
+
+/** The persisted cost carried by a session entry, or 0 for any other entry. */
+export function usageEntryCost(entry: unknown): number {
+	if (!entry || typeof entry !== "object") return 0;
+	const e = entry as { type?: string; customType?: string; data?: unknown };
+	if (e.type !== "custom" || e.customType !== USAGE_ENTRY_TYPE) return 0;
+	const cost = (e.data as { cost?: unknown } | undefined)?.cost;
+	return typeof cost === "number" && Number.isFinite(cost) ? cost : 0;
+}

package/extensions/lib/usage-tracker.ts

@@ -0,0 +1,67 @@
+/**
+ * Skill/command invocation counters (pure fs, no pi imports).
+ *
+ * `<plugin root>/usage.json`: `{version: 1, entries: {"<kind>:<key>":
+ * {count, lastUsedAt}}}`. Feeds the /plugins Installed tab's recency labels
+ * ("never used", "3× 120d") and its "Not used recently" grouping.
+ *
+ * Writes are a synchronous read-modify-write per invocation — Node is
+ * single-threaded and every fs call here is sync, so there is no interleaving
+ * window to debounce away; a timer-based debounce would only ADD an async gap
+ * (and a lost-write risk at process exit).
+ */
+
+import { join } from "node:path";
+import { readJsonFile, writeJsonAtomic } from "./atomic-write.ts";
+
+const FILE = "usage.json";
+
+export type UsageKind = "skill" | "command" | "mcpTool";
+
+export interface UsageEntry {
+	count: number;
+	lastUsedAt: string;
+}
+
+export function usageKey(kind: UsageKind, key: string): string {
+	return `${kind}:${key}`;
+}
+
+export function readUsage(root: string): Record<string, UsageEntry> {
+	const parsed = readJsonFile<{ entries?: Record<string, unknown> }>(join(root, FILE));
+	if (!parsed?.entries || typeof parsed.entries !== "object") return {};
+	const entries: Record<string, UsageEntry> = {};
+	for (const [key, value] of Object.entries(parsed.entries)) {
+		const entry = value as { count?: unknown; lastUsedAt?: unknown };
+		if (typeof entry?.count === "number" && typeof entry?.lastUsedAt === "string") {
+			entries[key] = { count: entry.count, lastUsedAt: entry.lastUsedAt };
+		}
+	}
+	return entries;
+}
+
+export function recordUsage(root: string, kind: UsageKind, key: string, now: Date = new Date()): void {
+	// Best-effort bookkeeping: a write failure (disk full, unwritable root)
+	// must never take down the skill/command invocation being recorded.
+	try {
+		const path = join(root, FILE);
+		const existing = readJsonFile<{ version?: unknown; entries?: Record<string, unknown> }>(path) ?? {};
+		const entries = { ...(typeof existing.entries === "object" && existing.entries ? existing.entries : {}) };
+		const id = usageKey(kind, key);
+		const previous = entries[id] as { count?: unknown } | undefined;
+		const count = typeof previous?.count === "number" ? previous.count + 1 : 1;
+		entries[id] = { count, lastUsedAt: now.toISOString() };
+		writeJsonAtomic(path, { ...existing, version: 1, entries });
+	} catch {
+		// Usage stats are display-only; losing one tick is fine.
+	}
+}
+
+/** "never used" | "1× today" | "3× 120d" — the Installed tab's recency label. */
+export function formatRecency(entry: UsageEntry | undefined, now: Date = new Date()): string {
+	if (!entry) return "never used";
+	const last = Date.parse(entry.lastUsedAt);
+	if (Number.isNaN(last)) return "never used";
+	const days = Math.max(0, Math.floor((now.getTime() - last) / 86_400_000));
+	return `${entry.count}× ${days === 0 ? "today" : `${days}d`}`;
+}