pi-ui-extend 0.1.2 → 0.1.4

package/README.md

@@ -16,8 +16,9 @@ The npm package is currently named `pi-ui-extend` and installs the `pix` CLI.
 
 ## Requirements
 
-- Node.js `24.x` (`24.16.0` is pinned for development).
-- A terminal with good Unicode support. JetBrainsMono Nerd Font is recommended for the default icon theme.
+- Node.js `>=22.19.0 <25` (`24.16.0` is pinned for development).
+- A terminal with good Unicode support. JetBrainsMono Nerd Font is recommended for the default icon theme; Pix can install it for the current user on macOS, Linux, and Windows.
+- Linux clipboard support: Pix first tries `wl-copy`, `xclip`, `xsel`, or `termux-clipboard-set`, then falls back to its bundled native clipboard package.
 - Optional for voice input: SoX (`rec`/`sox`), `ffmpeg`, or Linux `arecord`.
 
 Development uses `mise` when available. `.node-version` and `.nvmrc` are also provided for other Node version managers.
@@ -32,6 +33,16 @@ npm install -g pi-ui-extend --ignore-scripts
 
 The published package contains built JavaScript, the `pix` launcher, renderer extensions, documentation, and the bundled `pi-tools-suite` extension payload. Users do not need to clone the repository or build TypeScript locally.
 
+After installation, run the setup check when installing on a new machine:
+
+```bash
+pix install
+# or report only:
+pix install --check
+```
+
+`pix install` checks the icon font, `pi` CLI availability, and clipboard helpers. The `pix` launcher also prepends Pix's bundled dependency bin directory to `PATH`, so a package-manager install can use the bundled Pi CLI even when a separate global `pi` command is not present.
+
 On startup, Pix ensures the bundled suite is available at:
 
 ```text
@@ -185,7 +196,7 @@ Runtime requirements:
 
 - Optional npm package `vosk`. Pix installs or rebuilds it automatically with scripts enabled on first voice start if the native binding is missing.
 - A local recorder: SoX (`rec`/`sox`) preferred, or `ffmpeg`; Linux also supports `arecord`.
-- JetBrainsMono Nerd Font for default app icons. On macOS, Pix checks this at startup and can install the Homebrew cask `font-jetbrains-mono-nerd-font` when it is missing.
+- JetBrainsMono Nerd Font for default app icons. Pix checks this at startup and can install the font for the current user on macOS, Linux, and Windows when it is missing.
 
 If your terminal renders missing glyphs, start Pix with `PIX_USE_FALLBACK_ICONS=1` or set `iconTheme` to `fallback` in `~/.config/pi/pix.jsonc`.
 

package/bin/pix.mjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const minimumNodeVersion = [22, 19, 0];
 const minimumNodeVersionLabel = "22.19.0";
+const launcherPath = fileURLToPath(import.meta.url);
+const packageRoot = dirname(dirname(launcherPath));
 const mainPath = fileURLToPath(new URL("../dist/main.js", import.meta.url));
 const updatePath = fileURLToPath(new URL("../dist/app/update.js", import.meta.url));
+const installPath = fileURLToPath(new URL("../dist/app/install.js", import.meta.url));
 const distPath = dirname(mainPath);
 const rawArgs = process.argv.slice(2);
 const childArgs = [];
@@ -40,6 +43,15 @@ if (childArgs[0] === "update") {
 	process.exit(await runPixUpdateCli(childArgs.slice(1)));
 }
 
+if (childArgs[0] === "install" || childArgs[0] === "setup") {
+	if (!existsSync(installPath)) {
+		console.error("pix install is not built yet. Run `npm run build:pix` or update from a published package.");
+		process.exit(1);
+	}
+	const { runPixInstallCli } = await import(new URL("../dist/app/install.js", import.meta.url));
+	process.exit(await runPixInstallCli(childArgs.slice(1), { env: pixChildEnv() }));
+}
+
 if (!existsSync(mainPath)) {
 	console.error("pix is not built yet. Run `npm run build:pix` or `npm run watch:pix`.");
 	process.exit(1);
@@ -82,6 +94,7 @@ function isCurrentNodeSupported() {
 function startChild() {
 	child = spawn(process.execPath, [mainPath, ...childArgs], {
 		stdio: "inherit",
+		env: pixChildEnv(),
 	});
 
 	child.on("error", (error) => {
@@ -103,6 +116,16 @@ function startChild() {
 	});
 }
 
+function pixChildEnv() {
+	const env = { ...process.env };
+	const bundledBinPath = join(packageRoot, "node_modules", ".bin");
+	if (existsSync(bundledBinPath)) {
+		env.PATH = [bundledBinPath, env.PATH ?? ""].filter(Boolean).join(delimiter);
+		env.PIX_BUNDLED_PI_BIN = bundledBinPath;
+	}
+	return env;
+}
+
 function startDistPolling() {
 	const pollInterval = Number(process.env.PIX_RELOAD_POLL_MS ?? 1000);
 	distPollTimer = setInterval(() => {

package/dist/app/app.d.ts

@@ -19,7 +19,6 @@ export declare class PiUiExtendApp {
     private readonly extensionActions;
     private readonly pixConfig;
     private readonly outputFilters;
-    private readonly suppressPendingDcpIdMetadata;
     private readonly commandController;
     private readonly inputActions;
     private readonly inputController;

package/dist/app/app.js

@@ -1,6 +1,6 @@
 import { THEMES } from "../theme.js";
 import { InputEditor } from "../input-editor.js";
-import { compileOutputFilterPatterns, loadPixConfig, outputFiltersRemoveDcpIdMetadataLine, resolveToolRule, } from "../config.js";
+import { compileOutputFilterPatterns, loadPixConfig, resolveToolRule, } from "../config.js";
 import { AppCommandController } from "./command-controller.js";
 import { ConversationViewport } from "./conversation-viewport.js";
 import { EditorLayoutRenderer } from "./editor-layout-renderer.js";
@@ -64,7 +64,6 @@ export class PiUiExtendApp {
     extensionActions;
     pixConfig;
     outputFilters;
-    suppressPendingDcpIdMetadata;
     commandController;
     inputActions;
     inputController;
@@ -367,7 +366,6 @@ export class PiUiExtendApp {
             suppressExtensionWidget: (key) => this.extensionUiController.suppressWidget(key),
         });
         this.outputFilters = compileOutputFilterPatterns(this.pixConfig.outputFilters.patterns);
-        this.suppressPendingDcpIdMetadata = outputFiltersRemoveDcpIdMetadataLine(this.outputFilters);
         this.conversationViewport = new ConversationViewport({
             get entries() { return app.entries; },
             get session() { return app.runtime?.session; },
@@ -379,7 +377,6 @@ export class PiUiExtendApp {
             colors: this.theme.colors,
             pixConfig: this.pixConfig,
             outputFilters: this.outputFilters,
-            suppressPendingDcpIdMetadata: this.suppressPendingDcpIdMetadata,
             hasDynamicConversationBlock: () => this.popupMenus.hasDynamicConversationBlock(),
             isDynamicConversationBlock: (entry) => this.popupMenus.isDynamicConversationBlock(entry),
             renderInlineUserMessageMenu: (entry, context) => this.popupMenus.renderInlineUserMessageMenu(entry, context),
@@ -493,7 +490,7 @@ export class PiUiExtendApp {
                 void this.tabsController.closeTab(tabId);
             },
             toastEntry: (toastId) => this.toastController.toast.entry(toastId),
-            showToast: (message, kind) => this.showToast(message, kind),
+            showToast: (message, kind, options) => this.showToast(message, kind, options),
             dismissToast: (toastId) => this.toastController.dismissToast(toastId),
             refreshModelUsageStatus: () => this.refreshModelUsageStatusFromClick(),
             toggleAllThinkingExpanded: () => {
@@ -842,8 +839,8 @@ export class PiUiExtendApp {
             this.showToast("Failed to refresh model usage limits", "error");
         });
     }
-    showToast(message, kind = "info") {
-        this.toastController.showToast(message, kind);
+    showToast(message, kind = "info", options) {
+        this.toastController.showToast(message, kind, options);
     }
     clearToastTimers() {
         this.toastController.clearToastTimers();

package/dist/app/cli.js

@@ -3,12 +3,14 @@ import { parseThemeName } from "../theme.js";
 export function usage() {
     return `Usage: pix [--cwd <path>] [--no-session] [--session <path>] [--theme dark|light] [--model <provider/model[:thinking]>]
 	       pix update [--check] [--force]
+	       pix install [--check]
 	       npm run dev -- [--cwd <path>] [--no-session] [--session <path>] [--theme dark|light] [--model <provider/model[:thinking]>]
 
 Examples:
 	  pix --cwd ../pi-mono
 	  pix --cwd ../pi-mono --theme light --model anthropic/claude-sonnet-4-20250514:medium
-	  pix update --check`;
+	  pix update --check
+	  pix install --check`;
 }
 export function parseArgs(argv) {
     let cwd = process.cwd();

package/dist/app/clipboard.d.ts

@@ -1 +1,3 @@
 export declare function copyTextToClipboard(text: string): void;
+export declare function clipboardSupportAvailable(env?: NodeJS.ProcessEnv): boolean;
+export declare function clipboardInstallHint(): string;

package/dist/app/clipboard.js

@@ -1,4 +1,6 @@
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 export function copyTextToClipboard(text) {
     const commands = clipboardCommands();
     for (const [command, args] of commands) {
@@ -6,7 +8,24 @@ export function copyTextToClipboard(text) {
         if (!result.error && result.status === 0)
             return;
     }
-    throw new Error("No clipboard command found");
+    if (copyWithNativeClipboard(text))
+        return;
+    throw new Error(`No clipboard command found. ${clipboardInstallHint()}`);
+}
+export function clipboardSupportAvailable(env = process.env) {
+    if (clipboardCommands().some(([command]) => commandExists(command, env)))
+        return true;
+    return resolveNativeClipboardEntrypoint() !== undefined;
+}
+export function clipboardInstallHint() {
+    if (process.platform === "linux") {
+        return "Install wl-clipboard for Wayland or xclip/xsel for X11 (for example: sudo apt install wl-clipboard xclip xsel).";
+    }
+    if (process.platform === "darwin")
+        return "Install pbcopy or check macOS clipboard permissions.";
+    if (process.platform === "win32")
+        return "Install clip.exe or check Windows clipboard access.";
+    return "Install a platform clipboard command.";
 }
 function clipboardCommands() {
     switch (process.platform) {
@@ -19,6 +38,40 @@ function clipboardCommands() {
                 ["wl-copy", []],
                 ["xclip", ["-selection", "clipboard"]],
                 ["xsel", ["--clipboard", "--input"]],
+                ["termux-clipboard-set", []],
             ];
     }
 }
+function copyWithNativeClipboard(text) {
+    const entrypoint = resolveNativeClipboardEntrypoint();
+    if (!entrypoint)
+        return false;
+    const script = `
+		import { createRequire } from "node:module";
+		import { readFileSync } from "node:fs";
+		const require = createRequire(${JSON.stringify(import.meta.url)});
+		const clipboard = require(${JSON.stringify(entrypoint)});
+		await clipboard.setText(readFileSync(0, "utf8"));
+	`;
+    const result = spawnSync(process.execPath, ["--input-type=module", "-e", script], {
+        input: text,
+        stdio: ["pipe", "ignore", "ignore"],
+        timeout: 3_000,
+    });
+    return !result.error && result.status === 0;
+}
+function resolveNativeClipboardEntrypoint() {
+    try {
+        return require.resolve("@mariozechner/clipboard");
+    }
+    catch {
+        return undefined;
+    }
+}
+function commandExists(command, env) {
+    const names = process.platform === "win32" ? [command, command.replace(/\.exe$/iu, ".cmd"), command.replace(/\.exe$/iu, ".bat")] : [command];
+    return names.some((name) => spawnSync(process.platform === "win32" ? "where" : "sh", process.platform === "win32" ? [name] : ["-lc", `command -v ${shellQuote(name)}`], { env, stdio: "ignore" }).status === 0);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/app/conversation-entry-renderer.d.ts

@@ -11,7 +11,6 @@ export type ConversationEntryRenderOptions = {
     colors: Theme["colors"];
     pixConfig: PixConfig;
     outputFilters: readonly RegExp[];
-    suppressPendingDcpIdMetadata: boolean;
     superCompactTools?: boolean;
     allThinkingExpanded?: boolean;
     renderInlineUserMessageMenu: (entry: Extract<Entry, {

package/dist/app/conversation-entry-renderer.js

@@ -1,4 +1,4 @@
-import { applyOutputFilters, stripDcpDisplayMetadata, suppressPendingDcpIdMetadataLine } from "../config.js";
+import { applyOutputFilters } from "../config.js";
 import { renderMarkdownTextLines } from "../markdown-format.js";
 import { attachImageClickTargets } from "./image-click-targets.js";
 import { horizontalPaddingLayout, padHorizontalText, wrapText } from "./render-text.js";
@@ -65,7 +65,7 @@ function renderCustomEntry(entry, width) {
     }));
 }
 function renderAssistantLines(text, width, options) {
-    const displayText = displayAssistantText(text, options.outputFilters, options.suppressPendingDcpIdMetadata);
+    const displayText = applyOutputFilters(text, options.outputFilters).trimEnd();
     if (!displayText)
         return [];
     return renderMarkdownTextLines(displayText, width).map((line) => ({
@@ -75,7 +75,3 @@ function renderAssistantLines(text, width, options) {
         ...(line.syntaxHighlight ? { syntaxHighlight: line.syntaxHighlight } : {}),
     }));
 }
-function displayAssistantText(text, outputFilters, suppressPendingDcpIdMetadata) {
-    const filtered = stripDcpDisplayMetadata(applyOutputFilters(text, outputFilters)).trimEnd();
-    return suppressPendingDcpIdMetadata ? suppressPendingDcpIdMetadataLine(filtered) : filtered;
-}

package/dist/app/conversation-tool-renderer.js

@@ -1,4 +1,4 @@
-import { resolveColor, resolveToolRule, stripDcpDisplayMetadata } from "../config.js";
+import { resolveColor, resolveToolRule } from "../config.js";
 import { formatMarkdownTables, markdownSyntaxHighlightsForText } from "../markdown-format.js";
 import { renderToolDisplay } from "../tool-renderers/index.js";
 import { DEFAULT_THINKING_TOOL_RULE, SUBAGENT_STATUSES, THINKING_TOOL_NAME, TODO_TOOL_NAME } from "./constants.js";
@@ -47,8 +47,7 @@ export function renderConversationToolEntry(entry, width, options) {
 }
 export function renderThinkingEntry(entry, width, options) {
     const rule = resolveThinkingToolRule(options.pixConfig);
-    const displayText = stripDcpDisplayMetadata(entry.text);
-    const markdownText = displayText ? formatMarkdownTables(displayText, Math.max(1, width - 2)) : "";
+    const markdownText = entry.text ? formatMarkdownTables(entry.text, Math.max(1, width - 2)) : "";
     const expandedText = trimTrailingBlankLines(markdownText);
     const compactExpandedText = options.superCompactTools ? removeBlankLines(expandedText) : expandedText;
     const forceExpanded = Boolean(options.allThinkingExpanded);

package/dist/app/conversation-viewport.d.ts

@@ -12,7 +12,6 @@ export type ConversationViewportHost = {
     readonly colors: Theme["colors"];
     readonly pixConfig: PixConfig;
     readonly outputFilters: readonly RegExp[];
-    readonly suppressPendingDcpIdMetadata: boolean;
     readonly superCompactTools?: boolean;
     readonly allThinkingExpanded?: boolean;
     hasDynamicConversationBlock?(): boolean;

package/dist/app/conversation-viewport.js

@@ -65,7 +65,6 @@ export class ConversationViewport {
             colors: this.host.colors,
             pixConfig: this.host.pixConfig,
             outputFilters: this.host.outputFilters,
-            suppressPendingDcpIdMetadata: this.host.suppressPendingDcpIdMetadata,
             superCompactTools: Boolean(this.host.superCompactTools),
             allThinkingExpanded: Boolean(this.host.allThinkingExpanded),
             renderInlineUserMessageMenu: (userEntry, context) => this.host.renderInlineUserMessageMenu(userEntry, context),

package/dist/app/dcp-stats.js

@@ -1,22 +1,39 @@
 import { normalizeToolName, parseArgsText } from "../tool-renderers/utils.js";
+const NUDGE_TYPES = ["turn", "iteration", "context-soft", "context-strong"];
 export function formatDcpStatsToast(session) {
     const stats = collectDcpSessionStats(session);
-    const parts = [
-        `context ${formatContextUsage(stats)}`,
-        `freed ${formatCompactNumber(stats.tokensSaved)} tokens`,
-        `${stats.runs.toLocaleString()} ${plural(stats.runs, "run")}`,
-        stats.items > 0 ? `${stats.items.toLocaleString()} ${plural(stats.items, "item")}` : undefined,
-        stats.summaryTokens > 0 ? `${formatCompactNumber(stats.summaryTokens)} summary` : undefined,
-        stats.activeBlocks != null && stats.totalBlocks != null ? `blocks ${stats.activeBlocks}/${stats.totalBlocks}` : undefined,
-        stats.prunedTools > 0 ? `pruned ${stats.prunedTools.toLocaleString()} tools` : undefined,
-    ].filter((part) => Boolean(part));
-    return `DCP: ${parts.join(" · ")}`;
+    const nudgeStats = collectDcpNudgeStats(session);
+    const activeBlocks = stats.activeBlocks ?? 0;
+    const totalBlocks = stats.totalBlocks ?? stats.activeBlocks ?? 0;
+    const totalNudgeEvents = nudgeStats.emitted + nudgeStats.upgraded;
+    const activeAnchors = NUDGE_TYPES.reduce((sum, type) => sum + nudgeStats.activeByType[type], 0);
+    const lines = [
+        "DCP Session Statistics:",
+        `  Tokens saved (estimated): ${fmt(stats.tokensSaved)}`,
+        `  Total pruning operations: ${fmt(stats.totalPruneCount)}`,
+        `  Compression blocks active: ${activeBlocks} / ${totalBlocks} total`,
+        "  Manual mode: off",
+        "",
+        "Nudge telemetry:",
+        `  Sent: ${fmt(nudgeStats.emitted)} emitted, ${fmt(nudgeStats.upgraded)} upgraded`,
+        `  By type: ${NUDGE_TYPES.map((type) => `${type}=${fmt(nudgeStats.byType[type])}`).join(", ")}`,
+        `  Active anchors: ${fmt(activeAnchors)}${activeAnchors > 0 ? ` (${NUDGE_TYPES.map((type) => `${type}=${fmt(nudgeStats.activeByType[type])}`).join(", ")})` : ""}`,
+        `  Cleared after compress: ${fmt(nudgeStats.clearedEvents)} time${nudgeStats.clearedEvents === 1 ? "" : "s"} (${fmt(nudgeStats.clearedAnchors)} anchor${nudgeStats.clearedAnchors === 1 ? "" : "s"})`,
+        `  Compliance proxy: ${fmt(nudgeStats.clearedEvents)} compress-after-nudge / ${fmt(totalNudgeEvents)} nudge event${totalNudgeEvents === 1 ? "" : "s"} (${pct(nudgeStats.clearedEvents, totalNudgeEvents)})`,
+        nudgeStats.last
+            ? `  Last nudge: ${nudgeStats.last.type} ${nudgeStats.last.event} at ${formatDate(nudgeStats.last.createdAt)} (${formatContextPercent(nudgeStats.last.contextPercent)})`
+            : "  Last nudge: none recorded",
+        "",
+        `Context: ${formatContextUsage(stats)}`,
+    ];
+    return lines.join("\n");
 }
 function collectDcpSessionStats(session) {
     const usage = session.getContextUsage();
     const stats = {
         runs: 0,
         tokensSaved: 0,
+        totalPruneCount: 0,
         items: 0,
         summaryTokens: 0,
         prunedTools: 0,
@@ -24,9 +41,15 @@ function collectDcpSessionStats(session) {
         ...(usage?.contextWindow != null ? { contextWindow: usage.contextWindow } : {}),
         ...(usage?.percent != null ? { contextPercent: usage.percent } : {}),
     };
-    for (const entry of session.sessionManager.getBranch()) {
+    const branch = session.sessionManager.getBranch();
+    const latestState = latestCustomEntryData(branch, "dcp-state");
+    if (latestState)
+        applyDcpStateStats(stats, latestState);
+    for (const entry of branch) {
         if (entry.type !== "message")
             continue;
+        if (latestState)
+            continue;
         const message = entry.message;
         if (message.role !== "toolResult")
             continue;
@@ -39,6 +62,7 @@ function collectDcpSessionStats(session) {
             continue;
         stats.runs += 1;
         stats.tokensSaved += numberValue(result.tokensSaved) ?? 0;
+        stats.totalPruneCount = Math.max(stats.totalPruneCount, numberValue(result.totalPruneCount) ?? 0);
         stats.items += numberValue(result.itemCount) ?? sumDefined(numberValue(result.ranges), numberValue(result.messages)) ?? 0;
         stats.summaryTokens += numberValue(result.totalSummaryTokens) ?? 0;
         stats.prunedTools += numberValue(result.prunedTools) ?? 0;
@@ -60,6 +84,91 @@ function collectDcpSessionStats(session) {
     }
     return stats;
 }
+function applyDcpStateStats(stats, data) {
+    stats.tokensSaved = numberValue(data.tokensSaved) ?? stats.tokensSaved;
+    stats.totalPruneCount = numberValue(data.totalPruneCount) ?? stats.totalPruneCount;
+    const blocks = Array.isArray(data.compressionBlocks) ? data.compressionBlocks : undefined;
+    if (blocks) {
+        stats.totalBlocks = blocks.length;
+        stats.activeBlocks = blocks.filter((block) => isRecord(block) && block.active !== false).length;
+    }
+    if (Array.isArray(data.prunedToolIds))
+        stats.prunedTools = data.prunedToolIds.length;
+}
+function collectDcpNudgeStats(session) {
+    const stats = {
+        emitted: 0,
+        upgraded: 0,
+        clearedEvents: 0,
+        clearedAnchors: 0,
+        byType: { "turn": 0, "iteration": 0, "context-soft": 0, "context-strong": 0 },
+        activeByType: { "turn": 0, "iteration": 0, "context-soft": 0, "context-strong": 0 },
+    };
+    const branch = session.sessionManager.getBranch();
+    const latestState = latestCustomEntryData(branch, "dcp-state");
+    if (latestState)
+        applyActiveAnchorStats(stats, latestState);
+    for (const entry of branch) {
+        const data = customEntryData(entry, "dcp-nudge");
+        if (!data)
+            continue;
+        const event = data.event;
+        if ((event === "emitted" || event === "upgraded") && isNudgeType(data.type)) {
+            if (event === "emitted")
+                stats.emitted += 1;
+            else
+                stats.upgraded += 1;
+            stats.byType[data.type] += 1;
+            const createdAt = numberValue(data.createdAt);
+            const contextPercent = typeof data.contextPercent === "number" || data.contextPercent === null ? data.contextPercent : undefined;
+            if (!stats.last || (createdAt ?? 0) >= (stats.last.createdAt ?? 0)) {
+                stats.last = {
+                    type: data.type,
+                    event,
+                    ...(createdAt !== undefined ? { createdAt } : {}),
+                    ...(contextPercent !== undefined ? { contextPercent } : {}),
+                };
+            }
+        }
+        else if (event === "cleared") {
+            stats.clearedEvents += 1;
+            stats.clearedAnchors += Math.max(0, numberValue(data.clearedAnchors) ?? 0);
+        }
+    }
+    return stats;
+}
+function applyActiveAnchorStats(stats, data) {
+    stats.activeByType = { "turn": 0, "iteration": 0, "context-soft": 0, "context-strong": 0 };
+    const anchors = Array.isArray(data.nudgeAnchors) ? data.nudgeAnchors : [];
+    for (const anchor of anchors) {
+        if (isRecord(anchor) && isNudgeType(anchor.type))
+            stats.activeByType[anchor.type] += 1;
+    }
+    const last = isRecord(data.lastNudge) ? data.lastNudge : undefined;
+    if (last && isNudgeType(last.type) && !stats.last) {
+        const contextPercent = numberValue(last.contextPercent);
+        const createdAt = numberValue(last.createdAt);
+        stats.last = {
+            type: last.type,
+            event: "emitted",
+            ...(createdAt !== undefined ? { createdAt } : {}),
+            ...(contextPercent !== undefined ? { contextPercent: contextPercent * 100 } : {}),
+        };
+    }
+}
+function customEntryData(entry, customType) {
+    if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== customType)
+        return undefined;
+    return isRecord(entry.data) ? entry.data : undefined;
+}
+function latestCustomEntryData(entries, customType) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const data = customEntryData(entries[i], customType);
+        if (data)
+            return data;
+    }
+    return undefined;
+}
 function parseToolResultText(content) {
     const parsed = parseArgsText(textContent(content));
     return isRecord(parsed) ? parsed : undefined;
@@ -87,6 +196,29 @@ function formatContextUsage(stats) {
         return `${percentText} of ${formatCompactNumber(window)}`;
     return percentText;
 }
+function isNudgeType(value) {
+    return typeof value === "string" && NUDGE_TYPES.includes(value);
+}
+function fmt(n) {
+    return Math.round(n).toLocaleString();
+}
+function pct(numerator, denominator) {
+    if (denominator <= 0)
+        return "n/a";
+    return `${((numerator / denominator) * 100).toFixed(1)}%`;
+}
+function formatDate(ts) {
+    if (typeof ts !== "number" || !Number.isFinite(ts) || ts <= 0)
+        return "unknown time";
+    return new Date(ts).toLocaleString();
+}
+function formatContextPercent(value) {
+    if (value === null)
+        return "unknown context";
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "unknown context";
+    return `${value.toFixed(1)}% context`;
+}
 function numberValue(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -108,9 +240,6 @@ function formatPercent(value) {
 function trimDecimal(value) {
     return value.toFixed(1).replace(/\.0$/, "");
 }
-function plural(count, word) {
-    return count === 1 ? word : `${word}s`;
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/app/install.d.ts

@@ -0,0 +1,10 @@
+export type PixInstallCliOptions = {
+    checkOnly: boolean;
+    help: boolean;
+};
+export type PixInstallCliContext = {
+    env?: NodeJS.ProcessEnv;
+};
+export declare function pixInstallUsage(): string;
+export declare function parsePixInstallArgs(argv: readonly string[]): PixInstallCliOptions;
+export declare function runPixInstallCli(argv?: readonly string[], context?: PixInstallCliContext): Promise<number>;