@pellux/goodvibes-agent 0.1.0

package/src/renderer/semantic-diff.ts

@@ -0,0 +1,369 @@
+/**
+ * semantic-diff.ts — Functional change summary after file edits.
+ *
+ * Compares AST before/after an edit and extracts:
+ *   - Added / removed / modified functions, methods, classes, etc.
+ *   - Changed import specifiers
+ *   - New / removed exports
+ *
+ * Returns a compact SemanticDiff that can be rendered alongside a regular diff.
+ * Gracefully returns null when tree-sitter is unavailable or the language is
+ * unsupported — callers should treat null as "no semantic info available".
+ */
+
+import { TreeSitterService } from '@pellux/goodvibes-sdk/platform/intelligence';
+import { extractSymbols } from '@pellux/goodvibes-sdk/platform/intelligence';
+import type { SymbolInfo } from '@pellux/goodvibes-sdk/platform/intelligence';
+import { detectLanguage } from '@pellux/goodvibes-sdk/platform/intelligence';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type ChangeKind = 'added' | 'removed' | 'modified';
+
+export interface SymbolChange {
+  kind: ChangeKind;
+  symbolKind: SymbolInfo['kind'];
+  name: string;
+  /** Present for 'modified' — the old signature. */
+  oldSignature?: string;
+  /** Present for 'added' or 'modified' — the new signature. */
+  newSignature?: string;
+}
+
+export interface ImportChange {
+  kind: ChangeKind;
+  specifier: string; // the module path, e.g. './utils'
+  /** Specific named imports that changed, if determinable. */
+  names?: string[];
+}
+
+export interface SemanticDiff {
+  symbols: SymbolChange[];
+  imports: ImportChange[];
+  /** Convenience: total number of changes across all categories. */
+  totalChanges: number;
+}
+
+// ---------------------------------------------------------------------------
+// Import extraction (regex-based — fast, no grammar needed)
+// ---------------------------------------------------------------------------
+
+interface ParsedImport {
+  specifier: string;
+  names: string[];
+}
+
+/**
+ * Extract import specifiers and named imports from source text using a regex
+ * scan. Covers `import ... from '...'` and `import('...')` dynamic imports.
+ * Does not require tree-sitter.
+ */
+function extractImports(source: string): Map<string, ParsedImport> {
+  const map = new Map<string, ParsedImport>();
+
+  // Static imports: import { A, B } from './foo'
+  //                 import Foo from './foo'
+  //                 import * as Foo from './foo'
+  //                 import './side-effect'
+  const staticRe = /import\s+(?:([\s\S]*?)\s+from\s+)?['"]([^'"]+)['"]/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = staticRe.exec(source)) !== null) {
+    const clause = (m[1] ?? '').trim();
+    const specifier = m[2]!;
+    const names = parseNamedImports(clause);
+    const existing = map.get(specifier);
+    if (existing) {
+      for (const n of names) existing.names.push(n);
+    } else {
+      map.set(specifier, { specifier, names });
+    }
+  }
+
+  return map;
+}
+
+/** Parse `{ A, B as C }` or `* as Ns` or `Default` clauses into name strings. */
+function parseNamedImports(clause: string): string[] {
+  if (!clause) return [];
+  // Namespace import: * as Foo
+  if (clause.startsWith('*')) return [clause];
+  // Named imports: { A, B as C }
+  const braceMatch = clause.match(/\{([^}]*)\}/);
+  if (braceMatch) {
+    return braceMatch[1]!
+      .split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+  // Default import: Foo
+  return clause ? [clause] : [];
+}
+
+// ---------------------------------------------------------------------------
+// Symbol comparison
+// ---------------------------------------------------------------------------
+
+function diffSymbols(
+  before: SymbolInfo[],
+  after: SymbolInfo[],
+): SymbolChange[] {
+  const changes: SymbolChange[] = [];
+
+  // Key by qualified name (container.name or name)
+  const key = (s: SymbolInfo): string =>
+    s.container ? `${s.container}.${s.name}` : s.name;
+
+  const beforeMap = new Map<string, SymbolInfo>();
+  const afterMap = new Map<string, SymbolInfo>();
+
+  for (const s of before) beforeMap.set(key(s), s);
+  for (const s of after) afterMap.set(key(s), s);
+
+  // Removed or modified
+  for (const [k, bSym] of beforeMap) {
+    const aSym = afterMap.get(k);
+    if (!aSym) {
+      changes.push({
+        kind: 'removed',
+        symbolKind: bSym.kind,
+        name: k,
+        oldSignature: bSym.signature,
+      });
+    } else if (
+      bSym.signature !== aSym.signature ||
+      bSym.exported !== aSym.exported
+    ) {
+      changes.push({
+        kind: 'modified',
+        symbolKind: aSym.kind,
+        name: k,
+        oldSignature: bSym.signature,
+        newSignature: aSym.signature,
+      });
+    }
+  }
+
+  // Added
+  for (const [k, aSym] of afterMap) {
+    if (!beforeMap.has(k)) {
+      changes.push({
+        kind: 'added',
+        symbolKind: aSym.kind,
+        name: k,
+        newSignature: aSym.signature,
+      });
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Import comparison
+// ---------------------------------------------------------------------------
+
+function diffImports(
+  before: Map<string, ParsedImport>,
+  after: Map<string, ParsedImport>,
+): ImportChange[] {
+  const changes: ImportChange[] = [];
+
+  // Removed or modified
+  for (const [spec, bImp] of before) {
+    const aImp = after.get(spec);
+    if (!aImp) {
+      changes.push({ kind: 'removed', specifier: spec, names: bImp.names });
+    } else {
+      // Check if named imports changed
+      const bSet = new Set(bImp.names);
+      const aSet = new Set(aImp.names);
+      const added = aImp.names.filter(n => !bSet.has(n));
+      const removed = bImp.names.filter(n => !aSet.has(n));
+      if (added.length > 0 || removed.length > 0) {
+        const names: string[] = [
+          ...added.map(n => `+${n}`),
+          ...removed.map(n => `-${n}`),
+        ];
+        changes.push({ kind: 'modified', specifier: spec, names });
+      }
+    }
+  }
+
+  // Added
+  for (const [spec, aImp] of after) {
+    if (!before.has(spec)) {
+      changes.push({ kind: 'added', specifier: spec, names: aImp.names });
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare `beforeContent` and `afterContent` for the given `filePath` and
+ * return a SemanticDiff describing functional changes.
+ *
+ * Returns null when:
+ *   - The language is not supported by tree-sitter
+ *   - Tree-sitter is not initialized
+ *   - Parsing fails
+ *
+ * Import changes are always returned (regex-based, no grammar required).
+ */
+export async function computeSemanticDiff(
+  filePath: string,
+  beforeContent: string,
+  afterContent: string,
+): Promise<SemanticDiff | null> {
+  // Import diff is always available (regex-based)
+  const beforeImports = extractImports(beforeContent);
+  const afterImports = extractImports(afterContent);
+  const imports = diffImports(beforeImports, afterImports);
+
+  const langId = detectLanguage(filePath);
+  if (!langId) {
+    // No language support — return import changes only if any
+    if (imports.length === 0) return null;
+    return { symbols: [], imports, totalChanges: imports.length };
+  }
+
+  const svc = new TreeSitterService();
+
+  try {
+    await svc.initialize();
+  } catch {
+    logger.debug('computeSemanticDiff: tree-sitter init failed', { filePath });
+    if (imports.length === 0) return null;
+    return { symbols: [], imports, totalChanges: imports.length };
+  }
+
+  // Use a temporary key so we don't pollute the service cache with diff content.
+  // Include a nonce so concurrent calls for the same filePath don't collide.
+  const nonce = Math.random().toString(36).slice(2);
+  const beforeKey = `__semantic_diff_before__${nonce}_${filePath}`;
+  const afterKey = `__semantic_diff_after__${nonce}_${filePath}`;
+
+  try {
+    const [beforeTree, afterTree] = await Promise.all([
+      svc.parse(beforeKey, beforeContent, langId),
+      svc.parse(afterKey, afterContent, langId),
+    ]);
+
+    if (!beforeTree || !afterTree) {
+      if (imports.length === 0) return null;
+      return { symbols: [], imports, totalChanges: imports.length };
+    }
+
+    // loadLanguage returns from cache since parse() already loaded it
+    const lang = await svc.loadLanguage(langId);
+    if (!lang) {
+      if (imports.length === 0) return null;
+      return { symbols: [], imports, totalChanges: imports.length };
+    }
+
+    const beforeSymbols = extractSymbols(beforeTree, lang, langId);
+    const afterSymbols = extractSymbols(afterTree, lang, langId);
+    const symbols = diffSymbols(beforeSymbols, afterSymbols);
+
+    // Clean up temporary cache entries
+    svc.invalidate(beforeKey);
+    svc.invalidate(afterKey);
+
+    const totalChanges = symbols.length + imports.length;
+    if (totalChanges === 0) return null;
+
+    return { symbols, imports, totalChanges };
+  } catch (err) {
+    logger.error('computeSemanticDiff: comparison failed', {
+      filePath,
+      error: summarizeError(err),
+    });
+    svc.invalidate(beforeKey);
+    svc.invalidate(afterKey);
+    if (imports.length === 0) return null;
+    return { symbols: [], imports, totalChanges: imports.length };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Display formatting
+// ---------------------------------------------------------------------------
+
+const KIND_ICON: Record<SymbolInfo['kind'], string> = {
+  function:  'fn',
+  method:    'method',
+  class:     'class',
+  interface: 'iface',
+  type:      'type',
+  variable:  'var',
+  constant:  'const',
+  enum:      'enum',
+  property:  'prop',
+  namespace: 'ns',
+};
+
+const CHANGE_GLYPH: Record<ChangeKind, string> = {
+  added:    '+',
+  removed:  '-',
+  modified: '~',
+};
+
+/**
+ * Render a SemanticDiff as an array of compact summary strings, one change
+ * per line. Suitable for display in the diff panel status area or a tooltip.
+ *
+ * Format examples:
+ *   +  fn  renderDiffView
+ *   ~  method  DiffPanel.showDiff  (signature changed)
+ *   -  class  OldWidget
+ *   +  import  ./utils  { A, B }
+ *   ~  import  ./types  (+NewType, -OldType)
+ */
+export function formatSemanticDiff(diff: SemanticDiff): string[] {
+  const lines: string[] = [];
+
+  // Symbol changes first
+  for (const sc of diff.symbols) {
+    const glyph = CHANGE_GLYPH[sc.kind];
+    const icon = KIND_ICON[sc.symbolKind];
+    let line = `${glyph}  ${icon}  ${sc.name}`;
+    if (sc.kind === 'modified') {
+      line += '  (signature changed)';
+    }
+    lines.push(line);
+  }
+
+  // Import changes
+  for (const ic of diff.imports) {
+    const glyph = CHANGE_GLYPH[ic.kind];
+    let line = `${glyph}  import  ${ic.specifier}`;
+    if (ic.names && ic.names.length > 0) {
+      const nameList = ic.names.slice(0, 4).join(', ');
+      const overflow = ic.names.length > 4 ? ` +${ic.names.length - 4} more` : '';
+      line += `  { ${nameList}${overflow} }`;
+    }
+    lines.push(line);
+  }
+
+  return lines;
+}
+
+/**
+ * Render a one-line summary suitable for a status bar.
+ * Example: "3 changes: +fn renderX  ~method Foo.bar  -import ./old"
+ */
+export function formatSemanticDiffSummary(diff: SemanticDiff): string {
+  if (diff.totalChanges === 0) return '';
+  const parts = formatSemanticDiff(diff).slice(0, 3);
+  const overflow = diff.totalChanges > 3 ? `  +${diff.totalChanges - 3} more` : '';
+  return `${diff.totalChanges} semantic change${diff.totalChanges !== 1 ? 's' : ''}: ${parts.join('  ')}${overflow}`;
+}

package/src/renderer/session-picker-modal.ts

@@ -0,0 +1,127 @@
+/**
+ * renderSessionPickerModal — renders the /sessions picker modal as Line[]
+ * using ModalFactory.
+ *
+ * Shows a list of saved sessions with:
+ *   - name, timestamp (formatted), message count
+ * Footer hints: [Enter] Load  [d] Delete  [Esc] Close
+ */
+
+import type { Line } from '../types/grid.ts';
+import { ModalFactory } from './modal-factory.ts';
+import type { SessionPickerModal } from '../input/session-picker-modal.ts';
+import { formatTimestamp } from './modal-utils.ts';
+import { fitDisplay } from '../utils/terminal-width.ts';
+import { getOverlaySurfaceMetrics, getStableOverlayContentRows } from './overlay-viewport.ts';
+
+// ---------------------------------------------------------------------------
+// Renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the session picker modal as Line[] for overlay in the viewport.
+ *
+ * @param modal  SessionPickerModal state object.
+ * @param width  Terminal width.
+ */
+export function renderSessionPickerModal(
+  modal: SessionPickerModal,
+  width: number,
+  viewportHeight = 24,
+): Line[] {
+  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
+    chromeRows: 6,
+    minContentRows: 5,
+    maxContentRows: 9,
+  });
+  const boxMargin = metrics.margin;
+  const boxW = metrics.boxWidth;
+  const contentW = metrics.contentWidth;
+  const visibleRows = metrics.contentRows;
+  const targetContentRows = getStableOverlayContentRows(metrics.contentRows, 8);
+  modal.setVisibleRows(visibleRows);
+
+  const sections: import('./modal-factory.ts').ModalSection[] = [];
+
+  if (modal.sessions.length === 0) {
+    sections.push({
+      type: 'text',
+      content: 'No saved sessions.',
+      style: { fg: '244', dim: true },
+    });
+    sections.push({
+      type: 'text',
+      content: 'Use /save [name] to save the current session.',
+      style: { fg: '240', dim: true },
+    });
+  } else {
+    // Column widths: name(24) | timestamp(16) | messages(remaining)
+    const nameW = 24;
+    const tsW = 16;
+    const msgW = Math.max(4, contentW - nameW - tsW - 4); // 4 = separators/spaces
+
+    // Column header
+    const nameHdr = fitDisplay('Name', nameW);
+    const tsHdr   = fitDisplay('Saved', tsW);
+    const msgHdr  = fitDisplay('Msgs', msgW);
+    sections.push({
+      type: 'text',
+      content: `${nameHdr}  ${tsHdr}  ${msgHdr}`,
+      style: { fg: '240', dim: true },
+    });
+    sections.push({ type: 'separator' });
+
+    const visibleSessions = modal.sessions.slice(modal.scrollOffset, modal.scrollOffset + visibleRows);
+    const listItems: import('./modal-factory.ts').ModalListItem[] = visibleSessions.map((sess, idx) => {
+      const isSelected = modal.scrollOffset + idx === modal.selectedIndex;
+
+      const nameStr = fitDisplay(sess.name, nameW);
+
+      const tsStr = fitDisplay(formatTimestamp(sess.timestamp), tsW);
+      const msgStr = fitDisplay(String(sess.messageCount), msgW);
+
+      const label = `${nameStr}  ${tsStr}  ${msgStr}`;
+      return { label, selected: isSelected };
+    });
+
+    sections.push({ type: 'list', items: listItems });
+    if (modal.sessions.length > visibleRows) {
+      sections.push({ type: 'separator' });
+      sections.push({
+        type: 'text',
+        content: `[${modal.scrollOffset + 1}-${Math.min(modal.sessions.length, modal.scrollOffset + visibleRows)} of ${modal.sessions.length}]`,
+        style: { fg: '244', dim: true },
+      });
+    }
+  }
+
+  // Status message if present
+  if (modal.statusMessage) {
+    sections.push({ type: 'separator' });
+    sections.push({
+      type: 'text',
+      content: modal.statusMessage,
+      style: { fg: modal.deleteConfirmationTarget ? '#f59e0b' : '#00ffcc' },
+    });
+  }
+
+  if (modal.deleteConfirmationTarget) {
+    sections.push({
+      type: 'text',
+      content: `Deletion is armed for ${modal.deleteConfirmationTarget}. Move selection or press Esc to cancel.`,
+      style: { fg: '244', dim: true },
+    });
+  }
+
+  return ModalFactory.createModal(
+    {
+      title: 'Sessions',
+      width: boxW,
+      margin: boxMargin,
+      targetContentRows,
+      sections,
+      hints: ['[\u2191\u2193] Navigate', '[Enter] Load', '[d] Arm / Delete', '[Esc] Close'],
+    },
+    width,
+  );
+}

package/src/renderer/settings-modal-helpers.ts

@@ -0,0 +1,193 @@
+/**
+ * Pure formatting, label, and color helpers for renderSettingsModal.
+ * Extracted from settings-modal.ts to keep the renderer under the 800-line
+ * architecture cap. No layout logic lives here.
+ */
+
+import type { SettingEntry, McpEntry, SubscriptionEntry } from '../input/settings-modal.ts';
+import { SETTINGS_CATEGORIES } from '../input/settings-modal.ts';
+import { isSecretConfigKey, isSecretReferenceValue } from '../config/secret-config.ts';
+
+function maskSecretValue(value: string): string {
+  if (value.length === 0) return '(empty)';
+  if (isSecretReferenceValue(value)) return value;
+  if (value.length <= 4) return '••••';
+  return `${'•'.repeat(Math.min(12, Math.max(4, value.length - 4)))}${value.slice(-4)}`;
+}
+
+export function formatValue(entry: SettingEntry): string {
+  const val = entry.currentValue;
+  if (val === null || val === undefined) return '(unset)';
+  if (typeof val === 'boolean') return val ? 'true' : 'false';
+  if (typeof val === 'string' && isSecretConfigKey(entry.setting.key)) return maskSecretValue(val);
+  if (typeof val === 'string' && val === '') return '(empty)';
+  return String(val);
+}
+
+export function valueColor(entry: SettingEntry): string {
+  if (!entry.isDefault) return '#00ffcc'; // cyan-green = modified
+  return '244';                            // dim = default
+}
+
+export function flagStateColor(state: string, killed: boolean): string {
+  if (killed) return '#ef4444'; // red
+  if (state === 'enabled') return '#00ffcc'; // cyan-green
+  return '244'; // dim
+}
+
+export function mcpTrustColor(mode: McpEntry['trustMode']): string {
+  switch (mode) {
+    case 'allow-all':
+      return '#ef4444';
+    case 'ask-on-risk':
+      return '#eab308';
+    case 'constrained':
+      return '#00ffcc';
+    case 'blocked':
+      return '244';
+    default:
+      return '244';
+  }
+}
+
+export function subscriptionStateColor(state: SubscriptionEntry['state']): string {
+  switch (state) {
+    case 'active':
+      return '#00ffcc';
+    case 'pending':
+      return '#eab308';
+    case 'available':
+      return '#38bdf8';
+    default:
+      return '244';
+  }
+}
+
+export function inferSubscriptionRouteReason(entry: SubscriptionEntry): string | undefined {
+  if (entry.routeReason?.trim()) return entry.routeReason;
+  if (entry.state === 'active' && entry.oauthConfigured) {
+    return 'ambient key override enabled for this provider.';
+  }
+  if (entry.state === 'pending' && entry.oauthConfigured) {
+    return 'oauth configuration present; ambient key override will apply after activation.';
+  }
+  return undefined;
+}
+
+export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], string> = {
+  display: 'Display',
+  ui: 'UI',
+  provider: 'Provider',
+  subscriptions: 'Subscriptions',
+  behavior: 'Behavior',
+  storage: 'Storage',
+  permissions: 'Permissions',
+  orchestration: 'Orchestration',
+  wrfc: 'WRFC Delegation',
+  helper: 'Helper',
+  tts: 'TTS',
+  service: 'Service',
+  controlPlane: 'Control Plane',
+  httpListener: 'HTTP Listener',
+  web: 'Web',
+  batch: 'Batch',
+  automation: 'Automation',
+  watchers: 'Watchers',
+  runtime: 'Runtime',
+  telemetry: 'Telemetry',
+  cache: 'Cache',
+  mcp: 'MCP',
+  sandbox: 'External Sandbox',
+  surfaces: 'Surfaces',
+  cloudflare: 'Cloudflare',
+  release: 'Release',
+  danger: 'Danger',
+  tools: 'Tools',
+  flags: 'Feature Flags',
+  network: 'Network',
+};
+
+export const SETTING_LABELS: Partial<Record<string, string>> = {
+  'ui.systemMessages': 'System Message Target',
+  'ui.operationalMessages': 'Operational Message Target',
+  'ui.wrfcMessages': 'Delegated WRFC Message Target',
+  'ui.voiceEnabled': 'Voice Surface',
+  'behavior.autoCompactThreshold': 'Auto-Compact %',
+  'behavior.staleContextWarnings': 'Context Warnings',
+  'behavior.returnContextMode': 'Return Context',
+  'behavior.guidanceMode': 'Guidance Mode',
+  'storage.secretPolicy': 'Secret Policy',
+  'sandbox.vmBackend': 'External Sandbox Backend',
+  'sandbox.qemuBinary': 'External QEMU Binary',
+  'sandbox.qemuImagePath': 'External QEMU Image',
+  'sandbox.qemuExecWrapper': 'External QEMU Wrapper',
+  'sandbox.replJavaScriptCommand': 'REPL JS Command',
+  'tools.llmProvider': 'Tool LLM Provider',
+  'tools.llmModel': 'Tool LLM Model',
+  'tools.autoHeal': 'Auto-Heal',
+  'tools.defaultTokenBudget': 'Default Token Budget',
+  'tools.hooksFile': 'Hooks File',
+  'helper.enabled': 'Helper Enabled',
+  'helper.globalProvider': 'Helper Provider',
+  'helper.globalModel': 'Helper Model',
+  // Control Plane
+  'controlPlane.enabled': 'CP Enabled',
+  'controlPlane.hostMode': 'CP Host Mode',
+  'controlPlane.host': 'CP Host',
+  'controlPlane.port': 'CP Port',
+  'controlPlane.baseUrl': 'CP Base URL',
+  'controlPlane.streamMode': 'CP Stream Mode',
+  'controlPlane.allowRemote': 'CP Allow Remote',
+  'controlPlane.trustProxy': 'CP Trust Proxy',
+  'controlPlane.tls.mode': 'CP TLS Mode',
+  'controlPlane.tls.certFile': 'CP TLS Cert',
+  'controlPlane.tls.keyFile': 'CP TLS Key',
+  // HTTP Listener
+  'httpListener.hostMode': 'HTTP Host Mode',
+  'httpListener.host': 'HTTP Host',
+  'httpListener.port': 'HTTP Port',
+  'httpListener.trustProxy': 'HTTP Trust Proxy',
+  'httpListener.tls.mode': 'HTTP TLS Mode',
+  'httpListener.tls.certFile': 'HTTP TLS Cert',
+  // Web Server
+  'web.enabled': 'Web Enabled',
+  'web.hostMode': 'Web Host Mode',
+  'web.host': 'Web Host',
+  'web.port': 'Web Port',
+  'web.publicBaseUrl': 'Web Public Base URL',
+  'web.staticAssetsDir': 'Web Static Assets Dir',
+  'surfaces.ntfy.enabled': 'ntfy Enabled',
+  'surfaces.ntfy.baseUrl': 'ntfy Base URL',
+  'surfaces.ntfy.topic': 'ntfy Default Delivery Topic',
+  'surfaces.ntfy.chatTopic': 'ntfy Chat Topic',
+  'surfaces.ntfy.agentTopic': 'ntfy Agent Topic',
+  'surfaces.ntfy.remoteTopic': 'ntfy Daemon-Only Remote Topic',
+  'surfaces.ntfy.token': 'ntfy Token',
+  'surfaces.ntfy.defaultPriority': 'ntfy Default Priority',
+  'surfaces.homeassistant.enabled': 'Home Assistant Enabled',
+  'surfaces.homeassistant.instanceUrl': 'Home Assistant URL',
+  'surfaces.homeassistant.accessToken': 'Home Assistant Access Token',
+  'surfaces.homeassistant.webhookSecret': 'Home Assistant Webhook Secret',
+  'surfaces.homeassistant.defaultConversationId': 'Home Assistant Conversation ID',
+  'surfaces.homeassistant.remoteSessionTtlMs': 'Home Assistant Remote Session TTL',
+  'surfaces.homeassistant.deviceId': 'Home Assistant Device ID',
+  'surfaces.homeassistant.deviceName': 'Home Assistant Device Name',
+  'surfaces.homeassistant.eventType': 'Home Assistant Event Type',
+};
+
+export function getSettingLabel(entry: SettingEntry): string {
+  return SETTING_LABELS[entry.setting.key] ?? entry.setting.key.replace(/^[^.]+\./, '');
+}
+
+export function describeUiRouting(value: string): string {
+  switch (value) {
+    case 'panel':
+      return 'render in panels only';
+    case 'conversation':
+      return 'render inline in conversation';
+    case 'both':
+      return 'render in both conversation and panels';
+    default:
+      return value;
+  }
+}