@pi-unipi/utility 0.2.1 → 0.2.3

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.3",
   "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,8 @@ 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";
 
 /** Send a markdown response via pi.sendMessage */
 function sendResponse(pi: ExtensionAPI, markdown: string): void {
@@ -33,6 +35,68 @@ function sendResponse(pi: ExtensionAPI, markdown: string): void {
   );
 }
 
+/**
+ * Register name badge commands: /unipi:name-badge, /unipi:badge-gen.
+ */
+export function registerNameBadgeCommands(
+  pi: ExtensionAPI,
+  state: NameBadgeState,
+): void {
+  // ─── /unipi:name-badge — toggle badge overlay ───────────────────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.NAME_BADGE}`, {
+    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));
+    },
+  });
+}
+
 /**
  * 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,8 +20,11 @@ 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";
@@ -29,6 +32,9 @@ import { registerInfoScreen } from "./info-screen.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 +43,13 @@ const ALL_COMMANDS = [
   UTILITY_COMMANDS.CLEANUP,
   UTILITY_COMMANDS.ENV,
   UTILITY_COMMANDS.DOCTOR,
+  UTILITY_COMMANDS.NAME_BADGE,
+  UTILITY_COMMANDS.BADGE_GEN,
+  UTILITY_COMMANDS.BADGE_TOGGLE,
 ].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 +63,21 @@ export default function (pi: ExtensionAPI) {
     analytics.disable();
   });
 
+  // Initialize name badge state
+  const nameBadgeState = new NameBadgeState();
+
   // 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 +86,53 @@ 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);
+  });
+
+  // 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);
+    }
+  });
+
+  // Listen for badge generation requests from other modules (e.g., kanboard)
+  pi.on(UNIPI_EVENTS.BADGE_GENERATE_REQUEST as any, async (_event: any, ctx: any) => {
+    // Show badge overlay if not already visible
+    if (!nameBadgeState.isVisible() && ctx?.hasUI) {
+      await nameBadgeState.show(pi, ctx);
+    }
   });
 
   // Track command usage
@@ -84,6 +144,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 +153,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 +231,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.ts

@@ -0,0 +1,103 @@
+/**
+ * @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;
+}
+
+/** Default badge settings */
+const DEFAULT_SETTINGS: BadgeSettings = {
+  autoGen: true,
+  badgeEnabled: true,
+  agentTool: true,
+};
+
+/** 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,
+    };
+  } 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 |`,
+    "",
+    `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];
+  }
+}