@pi-unipi/utility 0.2.1 → 0.2.4

package/README.md

@@ -14,6 +14,8 @@ Comprehensive utility suite for the Pi coding agent — part of the Unipi extens
 | `/unipi:cleanup` | Clean stale DBs, temp files, old sessions |
 | `/unipi:env` | Show environment info (Node, Pi, OS, paths) |
 | `/unipi:doctor` | Run diagnostics across all modules |
+| `/unipi:name-badge` | Toggle name badge overlay (shows session name) |
+| `/unipi:badge-gen` | Generate session name via LLM and enable badge |
 
 ### Tools
 
@@ -59,6 +61,16 @@ pi install npm:@pi-unipi/unipi
 /unipi:doctor              # Run diagnostics
 ```
 
+### Name Badge
+
+```
+/unipi:name-badge          # Toggle the session name badge on/off
+/unipi:badge-gen           # Generate a session name via LLM
+```
+
+The badge is a persistent HUD overlay in the top-right corner showing the current session name.
+It auto-restores visibility on session restart.
+
 ### Batch Execution (Code)
 
 ```typescript
@@ -125,7 +137,9 @@ packages/utility/src/
 │   ├── capabilities.ts   # Terminal detection
 │   └── width.ts          # Width utilities
 ├── tui/
-│   └── settings-inspector.ts  # Settings overlay model
+│   ├── settings-inspector.ts  # Settings overlay model
+│   ├── name-badge.ts          # Name badge overlay component
+│   └── name-badge-state.ts    # Name badge state manager
 └── tools/
     ├── batch.ts          # Batch execution
     └── env.ts            # Environment info

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "license": "MIT",

package/src/commands.ts

@@ -20,6 +20,9 @@ import {
 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";
 
 /** Send a markdown response via pi.sendMessage */
 function sendResponse(pi: ExtensionAPI, markdown: string): void {
@@ -33,6 +36,104 @@ function sendResponse(pi: ExtensionAPI, markdown: string): void {
   );
 }
 
+/**
+ * Register name badge commands: /unipi:badge-name, /unipi:badge-gen.
+ */
+export function registerNameBadgeCommands(
+  pi: ExtensionAPI,
+  state: NameBadgeState,
+): void {
+  // ─── /unipi:badge-name — toggle badge overlay ───────────────────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.BADGE_NAME}`, {
+    description: "Toggle session name badge overlay",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Name badge requires an interactive UI.", "warning");
+        return;
+      }
+
+      const nowVisible = await state.toggle(pi, ctx);
+      ctx.ui.notify(
+        nowVisible ? "Name badge enabled" : "Name badge disabled",
+        "info",
+      );
+    },
+  });
+
+  // ─── /unipi:badge-gen — generate name via background agent ─────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.BADGE_GEN}`, {
+    description: "Generate session name via background agent and enable badge",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Badge generation requires an interactive UI.", "warning");
+        return;
+      }
+
+      await state.generate(pi, ctx);
+      ctx.ui.notify("Generating session name...", "info");
+    },
+  });
+
+  // ─── /unipi:badge-toggle — configure badge settings ─────────────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.BADGE_TOGGLE}`, {
+    description: "Configure badge settings (autoGen, badgeEnabled, agentTool)",
+    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 value = parts[1]?.toLowerCase();
+        if ("autoGen|badgeEnabled|agentTool".includes(key)) {
+          const boolValue = value === "on" || value === "true" || value === "1";
+          updateBadgeSetting(key, boolValue);
+          ctx.ui.notify(`Badge ${key} set to ${boolValue}`, "info");
+          return;
+        }
+      }
+
+      // Show current settings
+      const settings = readBadgeSettings();
+      sendResponse(pi, formatBadgeSettings(settings));
+    },
+  });
+
+  // ─── /unipi:badge-settings — TUI settings overlay ──────────────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.BADGE_SETTINGS}`, {
+    description: "Configure badge settings via TUI overlay",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Badge settings require an interactive UI.", "warning");
+        return;
+      }
+
+      ctx.ui.custom(
+        (tui: any, _theme: any, _keybindings: any, done: any) => {
+          const overlay = new BadgeSettingsTui();
+          overlay.onClose = () => done(undefined);
+          overlay.requestRender = () => tui.requestRender();
+          return {
+            render: (w: number) => overlay.render(w),
+            invalidate: () => overlay.invalidate(),
+            handleInput: (data: string) => {
+              overlay.handleInput(data);
+              tui.requestRender();
+            },
+          };
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "80%",
+            minWidth: 50,
+            anchor: "center",
+            margin: 2,
+          },
+        },
+      );
+    },
+  });
+}
+
 /**
  * Register all utility commands.
  */

package/src/index.ts

@@ -2,14 +2,14 @@
  * @pi-unipi/utility — Extension entry
  *
  * Comprehensive utilities suite for Pi coding agent:
- * - Commands: continue, reload, status, cleanup, env, doctor
- * - Tools: ctx_batch, ctx_env
+ * - Commands: continue, reload, status, cleanup, env, doctor, badge
+ * - Tools: ctx_batch, 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
+ * - TUI: settings inspector pattern, name badge
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
@@ -20,15 +20,24 @@ import {
   UTILITY_TOOLS,
   emitEvent,
   getPackageVersion,
+  type UnipiBadgeGenerateRequestEvent,
 } from "@pi-unipi/core";
-import { registerUtilityCommands } from "./commands.js";
+import { registerUtilityCommands, registerNameBadgeCommands } from "./commands.js";
+import { NameBadgeState } from "./tui/name-badge-state.js";
+import { readBadgeSettings } from "./tui/badge-settings.js";
 import { getLifecycle } from "./lifecycle/process.js";
 import { getAnalyticsCollector } from "./analytics/collector.js";
 import { registerInfoScreen } from "./info-screen.js";
 
+/** Re-export readBadgeSettings for cross-package use */
+export { readBadgeSettings } from "./tui/badge-settings.js";
+
 /** Package version */
 const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
 
+/** Whether we've seen the first user message (for auto badge generation) */
+let firstMessageSeen = false;
+
 /** All commands registered by this module */
 const ALL_COMMANDS = [
   UTILITY_COMMANDS.CONTINUE,
@@ -37,10 +46,14 @@ const ALL_COMMANDS = [
   UTILITY_COMMANDS.CLEANUP,
   UTILITY_COMMANDS.ENV,
   UTILITY_COMMANDS.DOCTOR,
+  UTILITY_COMMANDS.BADGE_NAME,
+  UTILITY_COMMANDS.BADGE_GEN,
+  UTILITY_COMMANDS.BADGE_TOGGLE,
+  UTILITY_COMMANDS.BADGE_SETTINGS,
 ].map((cmd) => `unipi:${cmd}`);
 
 /** All tools registered by this module */
-const ALL_TOOLS = [UTILITY_TOOLS.BATCH, UTILITY_TOOLS.ENV];
+const ALL_TOOLS = [UTILITY_TOOLS.BATCH, UTILITY_TOOLS.ENV, UTILITY_TOOLS.SET_SESSION_NAME];
 
 export default function (pi: ExtensionAPI) {
   // Initialize lifecycle manager
@@ -54,17 +67,23 @@ export default function (pi: ExtensionAPI) {
     analytics.disable();
   });
 
+  // Initialize name badge state
+  const nameBadgeState = new NameBadgeState();
+
+  // Capture session context for cross-event use (not needed if BADGE_GENERATE_REQUEST removed)
+
   // Register commands
   registerUtilityCommands(pi);
+  registerNameBadgeCommands(pi, nameBadgeState);
 
   // Register tools
-  registerUtilityTools(pi);
+  registerUtilityTools(pi, nameBadgeState);
 
   // Register info-screen group
   registerInfoScreen(pi);
 
-  // Session lifecycle — announce module
-  pi.on("session_start", async () => {
+  // Session lifecycle — announce module + restore badge
+  pi.on("session_start", async (_event, ctx) => {
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.UTILITY,
       version: VERSION,
@@ -73,6 +92,54 @@ export default function (pi: ExtensionAPI) {
     });
 
     analytics.recordModuleLoad(MODULES.UTILITY, VERSION);
+
+    // Restore name badge if it was visible in previous session
+    await nameBadgeState.restore(pi, ctx);
+
+    // Write model cache for TUI components
+    if ((ctx as any).modelRegistry) {
+      const { writeModelCache } = await import("@pi-unipi/core");
+      const registry = (ctx as any).modelRegistry;
+      const models = (registry.getAvailable?.() ?? registry.getAll())
+        .map((m: any) => ({ provider: m.provider, id: m.id, name: m.name }));
+      writeModelCache(models);
+    }
+  });
+
+  // First-message hook: auto-generate session name on first user message
+  pi.on("input", async (_event: any, ctx: any) => {
+    // Only trigger on first user message
+    if (firstMessageSeen) return;
+    firstMessageSeen = true;
+
+    // Check if auto generation is enabled
+    const settings = readBadgeSettings();
+    if (!settings.autoGen) return;
+
+    // Skip if badge already has a name
+    const sessionName = pi.getSessionName?.();
+    if (sessionName) return;
+
+    // Get first message text for context
+    const messageText = typeof _event?.content === "string"
+      ? _event.content
+      : Array.isArray(_event?.content)
+        ? _event.content
+            .filter((c: any) => c.type === "text")
+            .map((c: any) => c.text)
+            .join(" ")
+        : "";
+
+    // Emit event for subagents to spawn background agent
+    emitEvent(pi, UNIPI_EVENTS.BADGE_GENERATE_REQUEST, {
+      source: "input-hook",
+      conversationSummary: messageText.slice(0, 500),
+    });
+
+    // Show badge overlay if UI available
+    if (ctx?.hasUI && !nameBadgeState.isVisible()) {
+      await nameBadgeState.show(pi, ctx);
+    }
   });
 
   // Track command usage
@@ -84,6 +151,8 @@ export default function (pi: ExtensionAPI) {
 
   // Session shutdown cleanup
   pi.on("session_shutdown", async () => {
+    nameBadgeState.hide();
+    firstMessageSeen = false;
     await lifecycle.shutdown("session_shutdown");
   });
 }
@@ -91,7 +160,7 @@ export default function (pi: ExtensionAPI) {
 /**
  * Register utility tools.
  */
-function registerUtilityTools(pi: ExtensionAPI): void {
+function registerUtilityTools(pi: ExtensionAPI, nameBadgeState: NameBadgeState): void {
   // ctx_batch — atomic batch execution
   pi.registerTool({
     name: UTILITY_TOOLS.BATCH,
@@ -169,4 +238,53 @@ function registerUtilityTools(pi: ExtensionAPI): void {
       };
     },
   });
+
+  // set_session_name — set the session name for badge display
+  const badgeSettings = readBadgeSettings();
+  if (badgeSettings.agentTool) {
+    pi.registerTool({
+      name: UTILITY_TOOLS.SET_SESSION_NAME,
+      label: "Set Session Name",
+      description:
+        "Set the session name that appears in the badge overlay and session selector. " +
+        "Use this to give the current session a descriptive title. " +
+        "Name should be concise (max 5 words recommended).",
+      promptSnippet: "Set a name/title for the current session.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "The session name to set (max 5 words recommended).",
+          },
+        },
+        required: ["name"],
+      },
+      async execute(_toolCallId, params) {
+        const { name } = params as { name: string };
+        if (!name || typeof name !== "string") {
+          return {
+            content: [{ type: "text", text: "Error: name parameter is required and must be a string." }],
+            details: undefined,
+          };
+        }
+
+        const trimmed = name.trim();
+        if (trimmed.length === 0) {
+          return {
+            content: [{ type: "text", text: "Error: name cannot be empty." }],
+            details: undefined,
+          };
+        }
+
+        // Set the session name
+        nameBadgeState.setSessionName(pi, trimmed);
+
+        return {
+          content: [{ type: "text", text: `Session name set to: "${trimmed}"` }],
+          details: { name: trimmed },
+        };
+      },
+    });
+  }
 }

package/src/tui/badge-settings-tui.ts

@@ -0,0 +1,388 @@
+/**
+ * @pi-unipi/utility — Badge Settings TUI Overlay
+ *
+ * Interactive settings overlay for badge configuration.
+ * Three settings: auto-generate toggle, badge-enabled toggle, generation model selector.
+ * Model list loaded from shared model cache (~/.unipi/config/models-cache.json).
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { CachedModel } from "@pi-unipi/core";
+import { readModelCache } from "@pi-unipi/core";
+import {
+  readBadgeSettings,
+  writeBadgeSettings,
+  type BadgeSettings,
+} from "./badge-settings.js";
+
+/** ANSI escape codes */
+const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+  white: "\x1b[37m",
+};
+
+/** Toggle symbols */
+const TOGGLE_ON = `${ansi.green}●${ansi.reset}`;
+const TOGGLE_OFF = `${ansi.dim}○${ansi.reset}`;
+
+/** Active mode */
+type Mode = "settings" | "model-picker";
+
+/** Setting row types */
+interface BooleanSetting {
+  type: "boolean";
+  key: keyof BadgeSettings;
+  label: string;
+  description: string;
+  getValue: (s: BadgeSettings) => boolean;
+}
+
+interface ModelSetting {
+  type: "model";
+  key: "generationModel";
+  label: string;
+  description: string;
+}
+
+type SettingItem = BooleanSetting | ModelSetting;
+
+/** Settings list */
+const SETTINGS: SettingItem[] = [
+  {
+    type: "boolean",
+    key: "autoGen",
+    label: "Auto generate",
+    description: "Generate session name on first user message",
+    getValue: (s) => s.autoGen,
+  },
+  {
+    type: "boolean",
+    key: "badgeEnabled",
+    label: "Badge enabled",
+    description: "Show the name badge overlay",
+    getValue: (s) => s.badgeEnabled,
+  },
+  {
+    type: "model",
+    key: "generationModel",
+    label: "Generation model",
+    description: "Model to use for badge name generation",
+  },
+];
+
+/**
+ * Badge Settings TUI overlay.
+ * Implements the Component interface for use with ctx.ui.custom().
+ */
+export class BadgeSettingsTui implements Component {
+  private settings: BadgeSettings;
+  private mode: Mode = "settings";
+  private selectedIndex = 0;
+  private modelScrollOffset = 0;
+  private models: CachedModel[] = [];
+
+  /** Theme reference for rendering (set externally) */
+  private _theme: any = null;
+
+  /** Callback when overlay should close */
+  onClose?: () => void;
+
+  /** Callback to request a re-render */
+  requestRender?: () => void;
+
+  constructor() {
+    this.settings = readBadgeSettings();
+    this.models = readModelCache();
+  }
+
+  /**
+   * Set the pi-tui theme for styled rendering.
+   */
+  setTheme(theme: any): void {
+    this._theme = theme;
+  }
+
+  /**
+   * Invalidate cached render state.
+   */
+  invalidate(): void {
+    // No cached state to invalidate
+  }
+
+  /**
+   * Handle keyboard input.
+   */
+  handleInput(data: string): void {
+    if (this.mode === "settings") {
+      this.handleSettingsInput(data);
+    } else {
+      this.handleModelPickerInput(data);
+    }
+  }
+
+  /**
+   * Handle input in settings mode.
+   */
+  private handleSettingsInput(data: string): void {
+    switch (data) {
+      case "\x1b[A": // Up arrow
+      case "k":
+        this.selectedIndex =
+          (this.selectedIndex - 1 + SETTINGS.length) % SETTINGS.length;
+        break;
+      case "\x1b[B": // Down arrow
+      case "j":
+        this.selectedIndex = (this.selectedIndex + 1) % SETTINGS.length;
+        break;
+      case " ": // Space — toggle boolean settings
+        this.toggleCurrentSetting();
+        break;
+      case "\r": // Enter — open model picker or toggle
+        if (SETTINGS[this.selectedIndex].type === "model") {
+          this.enterModelPicker();
+        } else {
+          this.toggleCurrentSetting();
+        }
+        break;
+      case "\x1b": // Escape — close and save
+        this.save();
+        this.onClose?.();
+        break;
+    }
+  }
+
+  /**
+   * Handle input in model picker mode.
+   */
+  private handleModelPickerInput(data: string): void {
+    const allModels = this.getModelList();
+
+    switch (data) {
+      case "\x1b[A": // Up arrow
+      case "k":
+        this.selectedIndex =
+          (this.selectedIndex - 1 + allModels.length) % allModels.length;
+        this.adjustModelScroll(allModels.length);
+        break;
+      case "\x1b[B": // Down arrow
+      case "j":
+        this.selectedIndex = (this.selectedIndex + 1) % allModels.length;
+        this.adjustModelScroll(allModels.length);
+        break;
+      case "\r": // Enter — select model
+        this.selectModel();
+        break;
+      case "\x1b": // Escape — cancel picker
+        this.mode = "settings";
+        this.selectedIndex = SETTINGS.findIndex(
+          (s) => s.key === "generationModel",
+        );
+        break;
+    }
+  }
+
+  /**
+   * Toggle the currently selected boolean setting.
+   */
+  private toggleCurrentSetting(): void {
+    const item = SETTINGS[this.selectedIndex];
+    if (item.type !== "boolean") return;
+
+    const current = item.getValue(this.settings);
+    (this.settings as any)[item.key] = !current;
+    this.save();
+  }
+
+  /**
+   * Enter model picker mode.
+   */
+  private enterModelPicker(): void {
+    this.mode = "model-picker";
+    const allModels = this.getModelList();
+    const currentModel = this.settings.generationModel;
+    this.selectedIndex = allModels.findIndex((m) => m.id === currentModel);
+    if (this.selectedIndex < 0) this.selectedIndex = 0;
+    this.modelScrollOffset = 0;
+    this.adjustModelScroll(allModels.length);
+  }
+
+  /**
+   * Select the current model in the picker.
+   */
+  private selectModel(): void {
+    const allModels = this.getModelList();
+    const selected = allModels[this.selectedIndex];
+    if (selected) {
+      this.settings.generationModel = selected.id;
+      this.save();
+    }
+    this.mode = "settings";
+    this.selectedIndex = SETTINGS.findIndex((s) => s.key === "generationModel");
+  }
+
+  /**
+   * Get model list with "inherit" as first entry.
+   */
+  private getModelList(): Array<{ id: string; label: string }> {
+    const list: Array<{ id: string; label: string }> = [
+      { id: "inherit", label: "inherit (use parent model)" },
+    ];
+    for (const m of this.models) {
+      const fullId = `${m.provider}/${m.id}`;
+      list.push({
+        id: fullId,
+        label: m.name ? `${fullId} (${m.name})` : fullId,
+      });
+    }
+    return list;
+  }
+
+  /**
+   * Adjust scroll offset so the selected item is visible.
+   */
+  private adjustModelScroll(totalItems: number): void {
+    // Reserve ~10 lines for visible model list
+    const visibleLines = 10;
+    if (this.selectedIndex < this.modelScrollOffset) {
+      this.modelScrollOffset = this.selectedIndex;
+    } else if (this.selectedIndex >= this.modelScrollOffset + visibleLines) {
+      this.modelScrollOffset = this.selectedIndex - visibleLines + 1;
+    }
+    // Clamp
+    this.modelScrollOffset = Math.max(
+      0,
+      Math.min(this.modelScrollOffset, totalItems - visibleLines),
+    );
+  }
+
+  /**
+   * Save settings to disk.
+   */
+  private save(): void {
+    writeBadgeSettings(this.settings);
+  }
+
+  /**
+   * Render the overlay.
+   */
+  render(width: number): string[] {
+    const lines: string[] = [];
+    const innerWidth = Math.max(44, width - 2);
+
+    const padVisible = (content: string, targetWidth: number): string => {
+      const vw = visibleWidth(content);
+      const pad = Math.max(0, targetWidth - vw);
+      return content + " ".repeat(pad);
+    };
+
+    const add = (s: string) =>
+      lines.push(
+        `${ansi.cyan}│${ansi.reset}` +
+          padVisible(truncateToWidth(s, innerWidth), innerWidth) +
+          `${ansi.cyan}│${ansi.reset}`,
+      );
+
+    const addEmpty = () =>
+      lines.push(
+        `${ansi.cyan}│${ansi.reset}` +
+          " ".repeat(innerWidth) +
+          `${ansi.cyan}│${ansi.reset}`,
+      );
+
+    // Top border
+    lines.push(`${ansi.cyan}╭${"─".repeat(innerWidth)}╮${ansi.reset}`);
+
+    // Header
+    add(`${ansi.bold}${ansi.cyan}Badge Settings${ansi.reset}`);
+    add(`${ansi.dim}Configure badge generation behavior${ansi.reset}`);
+    addEmpty();
+
+    // Settings list
+    for (let i = 0; i < SETTINGS.length; i++) {
+      const item = SETTINGS[i];
+      const isSelected = i === this.selectedIndex && this.mode === "settings";
+      const selector = isSelected ? `${ansi.cyan}▸${ansi.reset}` : " ";
+
+      if (item.type === "boolean") {
+        const value = item.getValue(this.settings);
+        const toggle = value ? TOGGLE_ON : TOGGLE_OFF;
+        const labelColor = isSelected ? ansi.bold : ansi.dim;
+
+        add(
+          `${selector} ${toggle} ${labelColor}${item.label}${ansi.reset}`,
+        );
+        add(`   ${ansi.gray}${item.description}${ansi.reset}`);
+      } else if (item.type === "model") {
+        const labelColor = isSelected ? ansi.bold : ansi.dim;
+        const modelDisplay = this.settings.generationModel;
+
+        add(
+          `${selector} ${ansi.yellow}⚙${ansi.reset} ${labelColor}${item.label}${ansi.reset}: ${ansi.white}${modelDisplay}${ansi.reset}`,
+        );
+        add(`   ${ansi.gray}${item.description}${ansi.reset}`);
+        add(`   ${ansi.dim}Enter to select model${ansi.reset}`);
+      }
+    }
+
+    // Model picker (inline)
+    if (this.mode === "model-picker") {
+      addEmpty();
+      add(`${ansi.bold}${ansi.cyan}── Available Models ──${ansi.reset}`);
+
+      const allModels = this.getModelList();
+      const visibleLines = 10;
+      const start = this.modelScrollOffset;
+      const end = Math.min(start + visibleLines, allModels.length);
+
+      // Scroll indicator up
+      if (start > 0) {
+        add(`  ${ansi.dim}▲ ${start} more above${ansi.reset}`);
+      }
+
+      for (let i = start; i < end; i++) {
+        const m = allModels[i];
+        const isSelected = i === this.selectedIndex;
+        const selector = isSelected ? `${ansi.cyan}▸${ansi.reset}` : " ";
+        const labelColor = isSelected ? ansi.bold + ansi.white : ansi.dim;
+
+        add(
+          `${selector} ${labelColor}${m.label}${ansi.reset}`,
+        );
+      }
+
+      // Scroll indicator down
+      if (end < allModels.length) {
+        add(
+          `  ${ansi.dim}▼ ${allModels.length - end} more below${ansi.reset}`,
+        );
+      }
+    }
+
+    // Footer
+    addEmpty();
+
+    if (this.mode === "model-picker") {
+      add(
+        `${ansi.dim}↑↓ navigate • Enter select • Esc cancel${ansi.reset}`,
+      );
+    } else {
+      add(
+        `${ansi.dim}↑↓ navigate • Space toggle • Enter select model • Esc close${ansi.reset}`,
+      );
+      add(`${ansi.dim}Config: .unipi/config/badge.json${ansi.reset}`);
+    }
+
+    // Bottom border
+    lines.push(`${ansi.cyan}╰${"─".repeat(innerWidth)}╯${ansi.reset}`);
+
+    return lines;
+  }
+}

package/src/tui/badge-settings.ts

@@ -0,0 +1,108 @@
+/**
+ * @pi-unipi/utility — Badge Settings Manager
+ *
+ * Manages badge configuration stored in .unipi/config/badge.json.
+ * Settings: autoGen, badgeEnabled, agentTool
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Badge settings interface */
+export interface BadgeSettings {
+  /** Auto-generate session name on first user message */
+  autoGen: boolean;
+  /** Show the badge overlay */
+  badgeEnabled: boolean;
+  /** Enable the set_session_name tool for agents */
+  agentTool: boolean;
+  /** Model to use for badge name generation. "inherit" = parent model, or "provider/model-id" */
+  generationModel: string;
+}
+
+/** Default badge settings */
+const DEFAULT_SETTINGS: BadgeSettings = {
+  autoGen: true,
+  badgeEnabled: true,
+  agentTool: true,
+  generationModel: "inherit",
+};
+
+/** Badge settings file name */
+const BADGE_CONFIG_FILE = ".unipi/config/badge.json";
+
+/**
+ * Get the config file path relative to cwd.
+ */
+function getConfigPath(): string {
+  return path.resolve(process.cwd(), BADGE_CONFIG_FILE);
+}
+
+/**
+ * Read badge settings from disk.
+ * Returns defaults if file doesn't exist or is malformed.
+ */
+export function readBadgeSettings(): BadgeSettings {
+  try {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) return { ...DEFAULT_SETTINGS };
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return {
+      autoGen: typeof parsed.autoGen === "boolean" ? parsed.autoGen : DEFAULT_SETTINGS.autoGen,
+      badgeEnabled: typeof parsed.badgeEnabled === "boolean" ? parsed.badgeEnabled : DEFAULT_SETTINGS.badgeEnabled,
+      agentTool: typeof parsed.agentTool === "boolean" ? parsed.agentTool : DEFAULT_SETTINGS.agentTool,
+      generationModel: typeof parsed.generationModel === "string" ? parsed.generationModel : DEFAULT_SETTINGS.generationModel,
+    };
+  } catch {
+    return { ...DEFAULT_SETTINGS };
+  }
+}
+
+/**
+ * Write badge settings to disk.
+ * Creates .unipi/config/ directory if needed.
+ */
+export function writeBadgeSettings(settings: BadgeSettings): void {
+  try {
+    const configPath = getConfigPath();
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  } catch {
+    // Best effort
+  }
+}
+
+/**
+ * Update a single badge setting.
+ */
+export function updateBadgeSetting<K extends keyof BadgeSettings>(
+  key: K,
+  value: BadgeSettings[K],
+): BadgeSettings {
+  const settings = readBadgeSettings();
+  settings[key] = value;
+  writeBadgeSettings(settings);
+  return settings;
+}
+
+/**
+ * Format badge settings for display.
+ */
+export function formatBadgeSettings(settings: BadgeSettings): string {
+  const toggle = (v: boolean) => (v ? "✓ enabled" : "✗ disabled");
+  return [
+    "## Badge Settings",
+    "",
+    `| Setting | Status | Description |`,
+    `|---------|--------|-------------|`,
+    `| Auto Generate | ${toggle(settings.autoGen)} | Generate name on first message |`,
+    `| Badge Enabled | ${toggle(settings.badgeEnabled)} | Show badge overlay |`,
+    `| Agent Tool | ${toggle(settings.agentTool)} | Allow agents to call set_session_name |`,
+    `| Generation Model | ${settings.generationModel} | Model for badge name generation |`,
+    "",
+    `Config: \`${BADGE_CONFIG_FILE}\``,
+  ].join("\n");
+}

package/src/tui/name-badge-state.ts

@@ -0,0 +1,299 @@
+/**
+ * @pi-unipi/utility — Name Badge State Manager
+ *
+ * Manages the name badge overlay lifecycle:
+ * - Toggle visibility (persisted via pi.appendEntry)
+ * - Poll for session name changes every 1s
+ * - Restore visibility on session start
+ * - Generate session name via background agent event
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
+import { NameBadgeComponent } from "./name-badge.js";
+import { readBadgeSettings } from "./badge-settings.js";
+
+/** Overlay handle from ctx.ui.custom() */
+interface OverlayHandle {
+  requestRender?: () => void;
+  hide?: () => void;
+  setHidden?: (hidden: boolean) => void;
+  isHidden?: () => boolean;
+  focus?: () => void;
+  unfocus?: () => void;
+  isFocused?: () => boolean;
+}
+
+/** Persisted badge state */
+interface BadgePersistedState {
+  visible: boolean;
+}
+
+/** Entry type for persistence */
+const BADGE_ENTRY_TYPE = "name-badge";
+
+/** Polling interval in ms */
+const POLL_INTERVAL_MS = 1000;
+
+/** Name generation timeout in ms */
+const GEN_TIMEOUT_MS = 30_000;
+
+/**
+ * NameBadgeState — manages the name badge overlay.
+ *
+ * Usage:
+ *   const state = new NameBadgeState();
+ *   // In session_start: state.restore(pi, ctx);
+ *   // In session_shutdown: state.hide();
+ *   // Commands: state.toggle(pi, ctx), state.generate(pi, ctx);
+ */
+export class NameBadgeState {
+  private visible = false;
+  private currentName: string | null = null;
+  private overlayHandle: OverlayHandle | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private component: NameBadgeComponent | null = null;
+  private genTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /** Whether the badge is currently visible */
+  isVisible(): boolean {
+    return this.visible;
+  }
+
+  /**
+   * Toggle badge visibility.
+   * If hidden → show + start polling.
+   * If visible → hide + stop polling.
+   */
+  async toggle(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<boolean> {
+    if (this.visible) {
+      this.hide();
+      this.persist(pi, false);
+      return false;
+    } else {
+      await this.show(pi, ctx);
+      this.persist(pi, true);
+      return true;
+    }
+  }
+
+  /**
+   * Show the badge overlay and start polling.
+   */
+  async show(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<void> {
+    if (this.overlayHandle) return; // Already showing
+
+    const name = this.safeGetName(pi);
+    this.currentName = name;
+    this.visible = true;
+
+    // Store tui reference for requestRender wiring
+    let tuiRef: any = null;
+
+    ctx.ui.custom(
+      (tui: any, theme: any, _keybindings: any, _done: any) => {
+        tuiRef = tui;
+        const component = new NameBadgeComponent(name);
+        component.setTheme(theme);
+        this.component = component;
+
+        return {
+          render: (w: number) => component.render(w),
+          invalidate: () => component.invalidate(),
+          // No handleInput — display-only overlay
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "top-center",
+          width: "100%",
+          nonCapturing: true,
+          visible: (termWidth: number) => termWidth >= 20,
+        },
+        onHandle: (handle: OverlayHandle) => {
+          this.overlayHandle = handle;
+          // Wire requestRender now that handle exists
+          if (tuiRef) {
+            (this.overlayHandle as any).requestRender = () => tuiRef.requestRender();
+          }
+        },
+      },
+    );
+
+    this.startPolling(pi);
+  }
+
+  /**
+   * Hide the badge overlay and stop polling.
+   */
+  hide(): void {
+    this.stopPolling();
+    this.clearGenTimeout();
+
+    if (this.overlayHandle) {
+      try {
+        // Use hide() to permanently remove the overlay
+        if (typeof this.overlayHandle.hide === "function") {
+          this.overlayHandle.hide();
+        } else if (typeof this.overlayHandle.setHidden === "function") {
+          this.overlayHandle.setHidden(true);
+        }
+      } catch {
+        // Handle may already be invalid
+      }
+      this.overlayHandle = null;
+    }
+
+    this.component = null;
+    this.visible = false;
+    this.currentName = null;
+  }
+
+  /**
+   * Restore badge visibility from persisted state.
+   * Call on session_start.
+   */
+  async restore(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<void> {
+    try {
+      const entries = (ctx as any).sessionManager?.getEntries?.() ?? [];
+      const badgeEntry = entries.findLast(
+        (e: any) => e.type === "custom" && e.customType === BADGE_ENTRY_TYPE,
+      );
+
+      if (badgeEntry?.data?.visible) {
+        await this.show(pi, ctx);
+      }
+    } catch {
+      // If we can't read entries, just don't restore
+    }
+  }
+
+  /**
+   * Generate a session name via background agent.
+   * Emits BADGE_GENERATE_REQUEST event for subagents to handle.
+   * Also enables the badge overlay if not visible.
+   */
+  async generate(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+    conversationSummary?: string,
+  ): Promise<void> {
+    // Enable badge if not visible
+    if (!this.visible) {
+      await this.show(pi, ctx);
+      this.persist(pi, true);
+    }
+
+    // Clear any previous generation timeout
+    this.clearGenTimeout();
+
+    // Emit event for subagents to spawn background agent
+    emitEvent(pi, UNIPI_EVENTS.BADGE_GENERATE_REQUEST, {
+      source: "command",
+      conversationSummary,
+    });
+
+    // Set timeout — if name not set within 30s, give up
+    this.genTimeout = setTimeout(() => {
+      this.genTimeout = null;
+      // If name is still null after timeout, the agent didn't respond
+      if (this.currentName === null) {
+        // Badge stays with placeholder — no error needed
+      }
+    }, GEN_TIMEOUT_MS);
+  }
+
+  /**
+   * Directly set the session name via pi API.
+   * Used by the set_session_name tool.
+   */
+  setSessionName(pi: ExtensionAPI, name: string): void {
+    try {
+      pi.setSessionName(name);
+      // Update component immediately (don't wait for poll)
+      this.currentName = name;
+      this.component?.setName(name);
+      this.overlayHandle?.requestRender?.();
+      // Clear generation timeout if active
+      this.clearGenTimeout();
+    } catch {
+      // Best effort
+    }
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────
+
+  /**
+   * Start polling for name changes.
+   */
+  private startPolling(pi: ExtensionAPI): void {
+    if (this.pollTimer) return;
+
+    this.pollTimer = setInterval(() => {
+      const name = this.safeGetName(pi);
+
+      // Check if generation timeout should be cleared
+      if (name !== null && this.genTimeout) {
+        this.clearGenTimeout();
+      }
+
+      if (name !== this.currentName) {
+        this.currentName = name;
+        this.component?.setName(name);
+        this.overlayHandle?.requestRender?.();
+      }
+    }, POLL_INTERVAL_MS);
+  }
+
+  /**
+   * Stop polling.
+   */
+  private stopPolling(): void {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  /**
+   * Clear generation timeout.
+   */
+  private clearGenTimeout(): void {
+    if (this.genTimeout) {
+      clearTimeout(this.genTimeout);
+      this.genTimeout = null;
+    }
+  }
+
+  /**
+   * Safely get session name, returning null on error.
+   */
+  private safeGetName(pi: ExtensionAPI): string | null {
+    try {
+      return pi.getSessionName() ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Persist badge visibility state.
+   */
+  private persist(pi: ExtensionAPI, visible: boolean): void {
+    try {
+      pi.appendEntry(BADGE_ENTRY_TYPE, { visible } satisfies BadgePersistedState);
+    } catch {
+      // Persistence is best-effort
+    }
+  }
+}

package/src/tui/name-badge.ts

@@ -0,0 +1,117 @@
+/**
+ * @pi-unipi/utility — Name Badge Component
+ *
+ * Pure render component for the session name badge overlay.
+ * Displays a bordered box with opaque background and session name.
+ * Display-only — no input handling, no focus.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+/** Placeholder text when no session name is set */
+const PLACEHOLDER = "Set a name";
+
+/**
+ * Pad content to exact visible width.
+ */
+function padVisible(content: string, targetWidth: number): string {
+  const vw = visibleWidth(content);
+  const pad = Math.max(0, targetWidth - vw);
+  return content + " ".repeat(pad);
+}
+
+/**
+ * NameBadgeComponent — bordered box HUD overlay showing session name.
+ *
+ * Renders a proper box with opaque background:
+ * ╭──────────╮
+ * │   Best   │
+ * ╰──────────╯
+ */
+export class NameBadgeComponent implements Component {
+  private name: string | null;
+  private theme: Theme | null = null;
+  private cachedLines: string[] | null = null;
+  private cachedWidth = -1;
+
+  constructor(name: string | null) {
+    this.name = name;
+  }
+
+  /** Update the displayed name */
+  setName(name: string | null): void {
+    if (name !== this.name) {
+      this.name = name;
+      this.invalidate();
+    }
+  }
+
+  /** Store theme reference for reactive color updates */
+  setTheme(theme: Theme): void {
+    this.theme = theme;
+    this.invalidate();
+  }
+
+  /** Clear cached render lines */
+  invalidate(): void {
+    this.cachedLines = null;
+    this.cachedWidth = -1;
+  }
+
+  render(width: number): string[] {
+    // Return cached if width unchanged
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    const lines = this.renderBadge(width);
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  private renderBadge(width: number): string[] {
+    // Determine display text and color
+    let displayText: string;
+    let fgColor: string;
+    if (this.name) {
+      displayText = this.name;
+      fgColor = "accent";
+    } else {
+      displayText = PLACEHOLDER;
+      fgColor = "muted";
+    }
+
+    // Full-width box: borders take 2 cols
+    const innerWidth = Math.max(1, width - 2);
+    const maxTextWidth = Math.max(1, innerWidth - 4); // 2-cell pad each side
+
+    // Truncate name if needed
+    if (visibleWidth(displayText) > maxTextWidth) {
+      displayText = truncateToWidth(displayText, maxTextWidth - 1, "…");
+    }
+
+    // Center text within inner width
+    const textVw = visibleWidth(displayText);
+    const leftPad = Math.floor((innerWidth - textVw) / 2);
+    const rightPad = innerWidth - textVw - leftPad;
+
+    const border = (s: string) => this.theme ? this.theme.fg("accent" as any, s) : s;
+    const bgFn = (s: string) => this.theme ? this.theme.bg("customMessageBg" as any, s) : s;
+
+    const nameStyled = this.theme
+      ? this.theme.fg(fgColor as any, displayText)
+      : displayText;
+
+    // Build lines with opaque background spanning full width
+    const topLine = bgFn(border("╭" + "─".repeat(innerWidth) + "╮"));
+    const contentLine = bgFn(
+      border("│") + " ".repeat(leftPad) + nameStyled + " ".repeat(rightPad) + border("│"),
+    );
+    const bottomLine = bgFn(border("╰" + "─".repeat(innerWidth) + "╯"));
+
+    return [topLine, contentLine, bottomLine];
+  }
+}