@pi-unipi/utility 2.6.1 → 2.9.0

package/README.md

@@ -1,8 +1,6 @@
 # @pi-unipi/utility
 
-Environment info, diagnostics, cleanup, name badge, and diff rendering. The grab-bag package for maintaining your development environment and making tool output readable.
-
-The diff rendering is the standout feature — Shiki-powered syntax-highlighted diffs for `write` and `edit` tool output. Side-by-side view for edits, unified view for writes, with color presets and auto-fallback on narrow terminals.
+Environment info, diagnostics, cleanup, and the session name badge. The grab-bag package for maintaining your development environment and keeping an eye on provider cache behavior.
 
 ## Commands
 
@@ -15,7 +13,9 @@ The diff rendering is the standout feature — Shiki-powered syntax-highlighted
 | `/unipi:reload` | Explain how to reload extensions |
 | `/unipi:name-badge` | Toggle name badge overlay |
 | `/unipi:badge-gen` | Generate session name via LLM and enable badge |
-| `/unipi:util-settings` | Unified settings for badge and diff rendering |
+| `/unipi:badge-name` | Set the session name shown in the badge |
+| `/unipi:badge-settings` | Configure badge behavior |
+| `/unipi:util-settings` | Unified settings TUI (badge) |
 | `/unipi:prefix-cache` | Show privacy-safe request-prefix transitions and provider cache token counters |
 
 ### Examples
@@ -31,7 +31,7 @@ The diff rendering is the standout feature — Shiki-powered syntax-highlighted
 
 ## Special Triggers
 
-Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment.
+Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment. When Herdr is present, the badge module syncs the session name to the pane title.
 
 ## Provider prefix-cache diagnostics
 
@@ -41,71 +41,31 @@ The fingerprints are keyed HMAC-SHA-256 values using a random in-memory key that
 
 `/unipi:cleanup` includes private `~/.unipi/tool-results/` artifacts in the normal temporary-file retention policy (7 days by default). Use dry-run mode to review candidates before deletion.
 
-The diff rendering feature wraps Pi's built-in `write` and `edit` tools. When enabled, these tools show syntax-highlighted diffs instead of plain output. This is a transparent replacement — the agent doesn't need to know about it.
-
 ## Agent Tools
 
 | Tool | Description |
 |------|-------------|
-| `ctx_batch` | Atomic batch execution with rollback support |
 | `ctx_env` | Environment inspection for debugging |
-| `write` | Write file with syntax-highlighted diff (when diff enabled) |
-| `edit` | Edit file with split/unified diff view (when diff enabled) |
-
-### Batch Execution
-
-```typescript
-import { BatchBuilder } from "@pi-unipi/utility/tools/batch";
-
-const report = await new BatchBuilder()
-  .addCommand("search", { query: "refactor" })
-  .addTool("memory_search", { query: "patterns" })
-  .withOptions({ failFast: true, commandTimeoutMs: 30000 })
-  .execute(myExecutor);
-
-if (!report.success) {
-  console.log("Failed:", report.results.find(r => !r.success)?.error);
-}
-```
+| `set_session_name` | Set the session name for badge display (when badge agent-tool is enabled) |
 
 ## Configurables
 
-### Diff Rendering
+### Name Badge
 
 ```
 /unipi:util-settings        # Open unified settings TUI
 ```
 
-Or edit `.unipi/config/util-settings.json` directly:
+Or edit `.unipi/config/util-settings.json` directly (migrated automatically from the legacy `.unipi/config/badge.json` on first read):
 
 ```json
 {
-  "diff": {
-    "enabled": true,
-    "theme": "default",
-    "shikiTheme": "github-dark",
-    "splitMinWidth": 150
+  "badge": {
+    "badgeEnabled": true
   }
 }
 ```
 
-| Setting | Default | Options |
-|---------|---------|---------|
-| `enabled` | true | true/false |
-| `theme` | "default" | default, midnight, subtle, neon |
-| `shikiTheme` | "github-dark" | github-dark, dracula, one-dark-pro, catppuccin-mocha, nord, tokyo-night |
-| `splitMinWidth` | 150 | Minimum terminal width for split view |
-
-Environment variable overrides: `DIFF_ADD_BG`, `DIFF_REM_BG`, etc.
-
-Features:
-- Split view (side-by-side) for `edit`, auto-falls back to unified on narrow terminals
-- Unified view (stacked) for `write` overwrites
-- LRU cache (192 entries) for Shiki highlights
-- Large diff fallback (skip highlighting above 80k chars)
-
-### Name Badge
-
 The badge is a persistent HUD overlay in the top-right corner showing the current session name. It auto-restores visibility on session restart.
 
 ## Programmatic API
@@ -113,35 +73,9 @@ The badge is a persistent HUD overlay in the top-right corner showing the curren
 | Module | Path | Description |
 |--------|------|-------------|
 | ProcessLifecycle | `lifecycle/process` | Parent PID polling, orphan detection, signal handlers |
-| cleanupStale | `lifecycle/cleanup` | Stale DB/temp/session/cache cleanup with dry-run |
-| TTLCache | `cache/ttl-cache` | Memory or SQLite-backed TTL cache |
+| cleanupStale | `lifecycle/cleanup` | Stale DB/temp/session cleanup with dry-run |
 | AnalyticsCollector | `analytics/collector` | Privacy-respecting event collection with daily rollup |
 | runDiagnostics | `diagnostics/engine` | Cross-module health checks with plugin architecture |
-| detectCapabilities | `display/capabilities` | Terminal feature detection (color, Nerd Font, unicode) |
-| Width Utilities | `display/width` | ANSI-aware clamp, wrap, collapse, pad, center |
-
-### TTL Cache
-
-```typescript
-import { TTLCache } from "@pi-unipi/utility/cache/ttl-cache";
-
-const cache = new TTLCache({ defaultTtlMs: 60000 });
-await cache.set("key", { data: "value" });
-const value = await cache.get("key");
-```
-
-### Terminal Capabilities
-
-```typescript
-import { detectCapabilities, getIcon } from "@pi-unipi/utility/display/capabilities";
-
-const caps = detectCapabilities();
-console.log("Nerd Font:", caps.nerdFont);
-console.log("Truecolor:", caps.truecolor);
-console.log(getIcon("󰘳", "[OK]")); // Uses Nerd Font if available
-```
-
-Capability detection distinguishes basic color, xterm-256-compatible terminals, and truecolor-capable terminals. Apple Terminal is treated as color-capable but not truecolor-capable so renderers can fall back safely.
 
 ## Privacy
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "2.6.1",
-  "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
+  "version": "2.9.0",
+  "description": "Utility commands and tools for Pi coding agent \u2014 lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -36,24 +36,24 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.6.1",
-    "diff": "^7.0.0",
-    "shiki": "^4.0.2"
-  },
-  "devDependencies": {
-    "@types/diff": "^7.0.2"
+    "@pi-unipi/core": "2.9.0"
   },
+  "devDependencies": {},
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@earendil-works/pi-tui": "^0.80.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "typebox": "^1.1.38"
   },
   "scripts": {
     "test": "npx tsx --test tests/**/*.test.ts"
   },
   "pi": {
-    "extensions": [],
-    "skills": [],
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
     "prompts": [],
     "themes": []
   }

package/src/commands.ts

@@ -21,8 +21,7 @@ import { cleanupStale, formatCleanupReport } from "./lifecycle/cleanup.js";
 import { runDiagnostics, formatDiagnosticsReport } from "./diagnostics/engine.js";
 import { getEnvironmentInfo, formatEnvironmentInfo } from "./tools/env.js";
 import type { NameBadgeState } from "./tui/name-badge-state.js";
-import { readBadgeSettings, updateBadgeSetting, formatBadgeSettings } from "./tui/badge-settings.js";
-import { BadgeSettingsTui } from "./tui/badge-settings-tui.js";
+import { readBadgeSettings, updateBadgeSetting, formatBadgeSettings } from "./settings.js";
 import { UtilSettingsTui } from "./tui/util-settings-tui.js";
 
 /** Send a markdown response via pi.sendMessage */
@@ -77,14 +76,14 @@ export function registerNameBadgeCommands(
 
   // ─── /unipi:badge-toggle — configure badge settings ─────────────────────
   pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.BADGE_TOGGLE}`, {
-    description: "Configure badge settings (autoGen, badgeEnabled, agentTool)",
+    description: "Configure badge settings (autoGen, badgeEnabled, agentTool, herdrSync)",
     handler: async (args: string, ctx: ExtensionContext) => {
       // Parse args: /unipi:badge-settings [key] [on|off]
       const parts = args.trim().split(/\s+/);
       if (parts.length >= 2 && parts[0]) {
-        const key = parts[0] as "autoGen" | "badgeEnabled" | "agentTool";
+        const key = parts[0] as "autoGen" | "badgeEnabled" | "agentTool" | "herdrSync";
         const value = parts[1]?.toLowerCase();
-        if ("autoGen|badgeEnabled|agentTool".includes(key)) {
+        if ("autoGen|badgeEnabled|agentTool|herdrSync".includes(key)) {
           const boolValue = value === "on" || value === "true" || value === "1";
           updateBadgeSetting(key, boolValue);
           ctx.ui.notify(`Badge ${key} set to ${boolValue}`, "info");

package/src/herdr-sync.ts

@@ -0,0 +1,136 @@
+/**
+ * @pi-unipi/utility — Herdr pane title sync
+ *
+ * When running inside a Herdr pane, pushes the pi session name to Herdr's
+ * socket API (`pane.report_metadata` with `title`). Herdr displays the title
+ * in the pane border / agent panel — always visible, never scrolls away.
+ *
+ * This is the scroll-proof session name display: the in-TUI badge overlay
+ * scrolls with content (pi renders to the primary buffer), but Herdr's pane
+ * border is drawn by Herdr itself outside the terminal scrollback.
+ *
+ * Detection: Herdr sets HERDR_ENV=1 and HERDR_SOCKET_PATH + HERDR_PANE_ID
+ * in every pane it spawns (same env the official herdr-pi integration uses).
+ */
+
+import { createConnection } from "node:net";
+
+/** Push timeout — never block the agent on a slow socket. */
+const SEND_TIMEOUT_MS = 500;
+
+export interface HerdrEnv {
+  enabled: boolean;
+  socketPath?: string;
+  paneId?: string;
+  tabId?: string;
+}
+
+/** Read Herdr environment (call once per session_start, cheap). */
+export function detectHerdr(): HerdrEnv {
+  const env = process.env.HERDR_ENV;
+  const socketPath = process.env.HERDR_SOCKET_PATH;
+  const paneId = process.env.HERDR_PANE_ID;
+  const tabId = process.env.HERDR_TAB_ID;
+  if (env === "1" && socketPath && paneId) {
+    return { enabled: true, socketPath, paneId, tabId };
+  }
+  return { enabled: false };
+}
+
+function sendRequest(socketPath: string, request: unknown): Promise<void> {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      socket.destroy();
+      resolve();
+    };
+    const socket = createConnection(socketPath);
+    socket.on("error", finish);
+    socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", finish);
+    socket.on("end", finish);
+    const timeout = setTimeout(finish, SEND_TIMEOUT_MS);
+    timeout.unref?.();
+  });
+}
+
+let reportSeq = Date.now();
+
+/** Only rename the tab when its label is a default numeric one (1-3 digits) — never clobber a user-set name. */
+const DEFAULT_TAB_LABEL = /^\d{1,3}$/;
+
+async function fetchJson(socketPath: string, method: string, params: Record<string, unknown>, extract: (result: any) => Record<string, unknown> | null): Promise<Record<string, unknown> | null> {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (value: Record<string, unknown> | null) => {
+      if (done) return;
+      done = true;
+      socket.destroy();
+      resolve(value);
+    };
+    const socket = createConnection(socketPath);
+    let buffer = "";
+    socket.on("error", () => finish(null));
+    socket.on("connect", () =>
+      socket.write(
+        `${JSON.stringify({ id: `unipi:fetch:${method}:${Date.now()}`, method, params })}\n`,
+      ),
+    );
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString();
+      try {
+        const parsed = JSON.parse(buffer);
+        finish(extract(parsed?.result));
+      } catch {
+        /* keep buffering */
+      }
+    });
+    socket.on("end", () => finish(null));
+    const timeout = setTimeout(() => finish(null), SEND_TIMEOUT_MS);
+    timeout.unref?.();
+  });
+}
+
+/**
+ * Push the session name to Herdr as the pane title, and as the tab label
+ * when the tab still has its default numeric label.
+ * Fire-and-forget: never throws, resolves after send timeout at worst.
+ */
+export async function syncPaneTitle(env: HerdrEnv, sessionName: string | null): Promise<void> {
+  if (!env.enabled || !env.socketPath || !env.paneId) return;
+  reportSeq += 1;
+  const params: Record<string, unknown> = {
+    pane_id: env.paneId,
+    source: "unipi:badge",
+    seq: reportSeq,
+  };
+  if (sessionName) {
+    params.title = sessionName;
+  } else {
+    params.clear_title = true;
+  }
+  // Best effort — errors are swallowed by sendRequest's error handler.
+  await sendRequest(env.socketPath, {
+    id: `unipi:badge:title:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    method: "pane.report_metadata",
+    params,
+  });
+
+  // Also sync the tab label so the name is visible in the tab bar (single-pane
+  // tabs don't render pane borders, so the pane title alone is invisible there).
+  // Only rename when the label is still the default numeric one — a user-set
+  // name always wins.
+  if (sessionName && env.tabId) {
+    const tab = await fetchJson(env.socketPath, "tab.get", { tab_id: env.tabId }, (r) => r?.tab ?? null);
+    const label = tab?.label;
+    if (typeof label !== "string" || DEFAULT_TAB_LABEL.test(label)) {
+      await sendRequest(env.socketPath, {
+        id: `unipi:badge:tab:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+        method: "tab.rename",
+        params: { tab_id: env.tabId, label: sessionName },
+      });
+    }
+  }
+}

package/src/index.ts

@@ -3,13 +3,12 @@
  *
  * Comprehensive utilities suite for Pi coding agent:
  * - Commands: continue, reload, status, cleanup, env, doctor, badge
- * - Tools: ctx_batch, ctx_env, set_session_name
+ * - Tools: ctx_env, set_session_name
  * - Lifecycle: process management, stale cleanup
- * - Cache: TTL cache with optional persistence
  * - Analytics: lightweight event collection
  * - Diagnostics: cross-module health checks
- * - Display: terminal capabilities, width utilities
- * - TUI: settings inspector pattern, name badge
+ * - Prefix-cache observability: privacy-safe provider cache stats
+ * - TUI: util settings, name badge (incl. Herdr pane title sync)
  */
 
 import { dirname } from "node:path";
@@ -26,16 +25,14 @@ import {
 } from "@pi-unipi/core";
 import { registerUtilityCommands, registerNameBadgeCommands } from "./commands.js";
 import { NameBadgeState } from "./tui/name-badge-state.js";
-import { readBadgeSettings } from "./tui/badge-settings.js";
-import { readDiffSettings } from "./diff/settings.js";
-import { registerEnhancedWriteTool, registerEnhancedEditTool } from "./diff/wrapper.js";
+import { readBadgeSettings } from "./settings.js";
 import { getLifecycle } from "./lifecycle/process.js";
 import { getAnalyticsCollector } from "./analytics/collector.js";
 import { registerInfoScreen } from "./info-screen.js";
 import { PrefixCacheTracker, formatPrefixCacheStats } from "./prefix-cache.js";
 
 /** Re-export readBadgeSettings for cross-package use */
-export { readBadgeSettings } from "./tui/badge-settings.js";
+export { readBadgeSettings } from "./settings.js";
 
 /** Package version */
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
@@ -155,12 +152,15 @@ export default function (pi: ExtensionAPI) {
     // Restore name badge if it was visible in previous session
     await nameBadgeState.restore(pi, ctx);
 
-    // Register diff-enhanced tools if enabled
-    const diffSettings = readDiffSettings();
-    if (diffSettings.enabled) {
-      const cwd = process.cwd();
-      registerEnhancedWriteTool(pi, cwd);
-      registerEnhancedEditTool(pi, cwd);
+    // Auto-show badge on session start if enabled in settings and UI is available.
+    // The badge shows "Set a name" placeholder until a name is generated.
+    // Previously the badge only showed after the first agent_end, which meant it
+    // was absent on restart until the user sent a message.
+    if (ctx?.hasUI && !nameBadgeState.isVisible()) {
+      const badgeSettings = readBadgeSettings();
+      if (badgeSettings.badgeEnabled) {
+        await nameBadgeState.show(pi, ctx);
+      }
     }
 
     // Write model cache for TUI components
@@ -274,64 +274,6 @@ export default function (pi: ExtensionAPI) {
  * Register utility tools.
  */
 function registerUtilityTools(pi: ExtensionAPI, nameBadgeState: NameBadgeState): void {
-  // ctx_batch — atomic batch execution
-  pi.registerTool({
-    name: UTILITY_TOOLS.BATCH,
-    label: "Batch Execute",
-    description:
-      "Execute a batch of commands atomically with rollback support. " +
-      "Accepts an array of {type, name, args} objects. " +
-      "Options: failFast (default true), commandTimeoutMs, totalTimeoutMs.",
-    promptSnippet: "Run multiple commands as an atomic batch.",
-    parameters: {
-      type: "object",
-      properties: {
-        commands: {
-          type: "array",
-          items: {
-            type: "object",
-            properties: {
-              type: { type: "string", enum: ["command", "tool", "search"] },
-              name: { type: "string" },
-              args: { type: "object" },
-            },
-            required: ["type", "name"],
-          },
-        },
-        options: {
-          type: "object",
-          properties: {
-            failFast: { type: "boolean" },
-            commandTimeoutMs: { type: "number" },
-            totalTimeoutMs: { type: "number" },
-          },
-        },
-      },
-      required: ["commands"],
-    },
-    async execute(_toolCallId, params) {
-      const { commands, options } = params as unknown as {
-        commands: Array<{ type: string; name: string; args?: Record<string, unknown> }>;
-        options?: Record<string, unknown>;
-      };
-
-      // Tool implementation delegates to batch executor
-      // The actual executor must be provided by the host
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              "ctx_batch requires a command executor from the host environment. " +
-              `Received ${commands.length} commands. ` +
-              "Use BatchBuilder or executeBatch() directly in code.",
-          },
-        ],
-        details: { commands, options },
-      };
-    },
-  });
-
   // ctx_env — environment info
   pi.registerTool({
     name: UTILITY_TOOLS.ENV,

package/src/lifecycle/cleanup.ts

@@ -4,7 +4,7 @@
  * Cleans stale DBs, temp files, old sessions across all unipi modules.
  */
 
-import { existsSync, statSync, readdirSync, unlinkSync, rmdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, unlinkSync, rmSync } from "node:fs";
 import { join, resolve, basename } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import type { CleanupReport, CleanupResult, CleanupOptions } from "../types.js";
@@ -229,21 +229,7 @@ function cleanSessions(options: Required<CleanupOptions>): CleanupResult {
         result.paths.push(fullPath);
         if (!options.dryRun) {
           try {
-            // Remove directory contents then directory
-            const removeRecursive = (dir: string) => {
-              const items = readdirSync(dir);
-              for (const item of items) {
-                const itemPath = join(dir, item);
-                const itemStats = statSync(itemPath);
-                if (itemStats.isDirectory()) {
-                  removeRecursive(itemPath);
-                } else {
-                  unlinkSync(itemPath);
-                }
-              }
-              rmdirSync(dir);
-            };
-            removeRecursive(fullPath);
+            rmSync(fullPath, { recursive: true, force: true });
             result.removed++;
           } catch {
             // Best effort