@tyvm/knowhow 0.0.110 → 0.0.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.110",
+  "version": "0.0.112",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/scripts/test-repetition-hint.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env ts-node
+/**
+ * Test script: runs the repetition hint processor logic against a real agent metadata file
+ * and prints whether the hint would fire and why/why not.
+ *
+ * Usage:
+ *   npx ts-node scripts/test-repetition-hint.ts [path-to-metadata.json]
+ */
+
+import * as fs from "fs";
+
+const metadataPath =
+  process.argv[2] ||
+  "/Users/micah/dev/knowhow-web/.knowhow/processes/agents/1779684572-can-you-try-setting-mysql-postgres-this-sandbox-with/metadata.json";
+
+interface ToolCall {
+  id: string;
+  type: string;
+  function: {
+    name: string;
+    arguments: string | Record<string, any>;
+  };
+}
+
+interface Message {
+  role: string;
+  content?: string;
+  tool_calls?: ToolCall[];
+}
+
+// ---- Replica of processor logic (mirrors CustomVariables.ts) ----
+
+function extractStringValues(obj: any, results: string[] = []): string[] {
+  if (typeof obj === "string") {
+    results.push(obj);
+  } else if (Array.isArray(obj)) {
+    for (const item of obj) extractStringValues(item, results);
+  } else if (obj && typeof obj === "object") {
+    for (const val of Object.values(obj)) extractStringValues(val, results);
+  }
+  return results;
+}
+
+function getToolCallStrings(toolCall: ToolCall): string[] {
+  try {
+    const args = toolCall.function.arguments;
+    const parsed = typeof args === "string" ? JSON.parse(args) : args;
+    return extractStringValues(parsed);
+  } catch {
+    const args = toolCall.function.arguments;
+    return [typeof args === "string" ? args : JSON.stringify(args)];
+  }
+}
+
+function collectToolCallStrings(
+  messages: Message[],
+  minLength: number
+): Array<{ value: string; toolName: string }> {
+  const collected: Array<{ value: string; toolName: string }> = [];
+  for (const message of messages) {
+    if (!message.tool_calls) continue;
+    for (const toolCall of message.tool_calls) {
+      const strings = getToolCallStrings(toolCall);
+      for (const str of strings) {
+        if (str.length >= minLength) {
+          collected.push({ value: str, toolName: toolCall.function.name });
+        }
+      }
+    }
+  }
+  return collected;
+}
+
+function longestCommonSubstring(a: string, b: string, minLength: number): string | null {
+  let best = "";
+  for (let i = 0; i < a.length - minLength + 1; i++) {
+    for (let j = a.length; j > i + minLength - 1; j--) {
+      const sub = a.slice(i, j);
+      if (sub.length <= best.length) break; // already found longer, skip shorter
+      if (b.includes(sub)) {
+        best = sub;
+        break;
+      }
+    }
+  }
+  return best.length >= minLength ? best : null;
+}
+
+function runProcessor(
+  messages: Message[],
+  minLength = 50,
+  minRepetitions = 2,
+  minSubstringLength = 50
+): { wouldHint: boolean; repeatedTools: string[]; details: Map<string, { count: number; tools: Set<string> }> } {
+  const stringCounts = new Map<string, { count: number; tools: Set<string> }>();
+  const toolStrings = collectToolCallStrings(messages, minLength);
+
+  // Step 1: exact full-string matches
+  for (const { value, toolName } of toolStrings) {
+    const existing = stringCounts.get(value);
+    if (existing) {
+      existing.count++;
+      existing.tools.add(toolName);
+    } else {
+      stringCounts.set(value, { count: 1, tools: new Set([toolName]) });
+    }
+  }
+
+  // Step 2: repeated substrings across different full strings
+  // e.g. the same JWT embedded in many different commands
+  const substringCounts = new Map<string, { count: number; tools: Set<string> }>();
+  for (let i = 0; i < toolStrings.length; i++) {
+    for (let j = i + 1; j < toolStrings.length; j++) {
+      const a = toolStrings[i];
+      const b = toolStrings[j];
+      if (a.value === b.value) continue; // already handled by exact match
+      const common = longestCommonSubstring(a.value, b.value, minSubstringLength);
+      if (common) {
+        const existing = substringCounts.get(common);
+        if (existing) {
+          existing.count++;
+          existing.tools.add(a.toolName);
+          existing.tools.add(b.toolName);
+        } else {
+          substringCounts.set(common, { count: 1, tools: new Set([a.toolName, b.toolName]) });
+        }
+      }
+    }
+  }
+
+  // Merge substring counts: count = number of unique pairs, count+1 = number of occurrences
+  for (const [sub, info] of substringCounts.entries()) {
+    if (info.count + 1 >= minRepetitions && !stringCounts.has(sub)) {
+      stringCounts.set(sub, { count: info.count + 1, tools: info.tools });
+    }
+  }
+
+  // Find entries that exceed the repetition threshold
+  const repeatedTools: string[] = [];
+  for (const [, info] of stringCounts.entries()) {
+    if (info.count >= minRepetitions) {
+      for (const toolName of info.tools) {
+        if (!repeatedTools.includes(toolName)) repeatedTools.push(toolName);
+      }
+    }
+  }
+
+  return { wouldHint: repeatedTools.length > 0, repeatedTools, details: stringCounts };
+}
+
+// ---- Main ----
+
+const raw = fs.readFileSync(metadataPath, "utf-8");
+const metadata = JSON.parse(raw);
+const threads: Message[][] = metadata.threads || [];
+
+console.log(`\n=== Repetition Hint Processor Test ===`);
+console.log(`File: ${metadataPath}`);
+console.log(`Threads: ${threads.length}`);
+
+for (let ti = 0; ti < threads.length; ti++) {
+  const thread = threads[ti];
+  const toolCallMsgs = thread.filter((m) => m.tool_calls && m.tool_calls.length > 0);
+  console.log(`\n--- Thread ${ti}: ${thread.length} messages, ${toolCallMsgs.length} with tool calls ---`);
+
+  // Run with OLD logic (exact matches only)
+  console.log(`\n[OLD Processor] exact full-string matches only, minLength=50, minRepetitions=2`);
+  const oldResult = runProcessor(thread, 50, 2, Infinity);
+  if (oldResult.wouldHint) {
+    console.log(`✅ Would hint! Repeated tools: ${oldResult.repeatedTools.join(", ")}`);
+  } else {
+    console.log(`❌ Would NOT hint (bug - missed embedded repetitions).`);
+  }
+
+  // Run with NEW logic (exact + substring)
+  console.log(`\n[NEW Processor] exact + substring matching, minLength=50, minRepetitions=2, minSubstringLength=50`);
+  const newResult = runProcessor(thread, 50, 2, 50);
+  if (newResult.wouldHint) {
+    console.log(`✅ Would hint! Repeated tools: ${newResult.repeatedTools.join(", ")}`);
+    // Show top repeated substrings
+    const repeated = Array.from(newResult.details.entries())
+      .filter(([, info]) => info.count >= 2)
+      .sort((a, b) => b[1].count - a[1].count)
+      .slice(0, 5);
+    console.log(`\n  Top repeated values (count, tools, preview):`);
+    for (const [str, info] of repeated) {
+      console.log(`    count=${info.count}, tools=${[...info.tools].join(",")}`);
+      console.log(`    value=${JSON.stringify(str.slice(0, 120))}`);
+    }
+  } else {
+    console.log(`❌ Would NOT hint.`);
+    // Show top large strings for diagnosis
+    const toolStrings = collectToolCallStrings(thread, 50);
+    console.log(`\n  Total large strings in tool calls: ${toolStrings.length}`);
+    const top = toolStrings.slice(0, 3);
+    for (const { value, toolName } of top) {
+      console.log(`    tool=${toolName}, len=${value.length}, preview=${JSON.stringify(value.slice(0, 100))}`);
+    }
+  }
+
+  // Check for Bearer tokens specifically
+  console.log(`\n[Bearer Token Check]`);
+  const jwtMap = new Map<string, { count: number; tools: Set<string> }>();
+  const jwtPattern = /Bearer ([\w\-\.]+)/;
+  for (const msg of thread) {
+    if (!msg.tool_calls) continue;
+    for (const tc of msg.tool_calls) {
+      const args = typeof tc.function.arguments === "string"
+        ? tc.function.arguments
+        : JSON.stringify(tc.function.arguments);
+      const match = jwtPattern.exec(args);
+      if (match) {
+        const jwt = match[1];
+        const existing = jwtMap.get(jwt);
+        if (existing) {
+          existing.count++;
+          existing.tools.add(tc.function.name);
+        } else {
+          jwtMap.set(jwt, { count: 1, tools: new Set([tc.function.name]) });
+        }
+      }
+    }
+  }
+  if (jwtMap.size > 0) {
+    for (const [jwt, info] of jwtMap.entries()) {
+      console.log(`  ⚠️  Bearer token appears ${info.count} times in: ${[...info.tools].join(", ")}`);
+      console.log(`     ${jwt.slice(0, 80)}...`);
+    }
+  } else {
+    console.log(`  No Bearer tokens found in tool calls.`);
+  }
+}
+
+console.log("\n=== Done ===\n");

package/src/auth/browserLogin.ts

@@ -3,6 +3,7 @@ import { exec } from "child_process";
 import { promisify } from "util";
 import * as os from "os";
 import * as fs from "fs";
+import * as path from "path";
 import { KNOWHOW_API_URL } from "../services/KnowhowClient";
 import { Spinner } from "./spinner";
 import { BrowserLoginError } from "./errors";
@@ -21,6 +22,8 @@ interface SessionStatusResponse {
 
 interface RetrieveTokenResponse {
   jwt: string;
+  requiresDeviceConfirmation?: boolean;
+  jwtSessionId?: string;
 }
 
 export class BrowserLoginService {
@@ -102,9 +105,32 @@ export class BrowserLoginService {
               `${this.baseUrl}/api/cli-login/session/${sessionData.sessionId}/token`
             );
 
-            const jwt = tokenResponse.data.jwt;
-            await this.storeJwt(jwt);
+            const tokenData = tokenResponse.data as RetrieveTokenResponse;
             spinner.stop();
+
+            if (tokenData.requiresDeviceConfirmation) {
+              // Token was issued but the device needs confirmation via email code.
+              // Store it now so it's ready once confirmed.
+              if (tokenData.jwt) {
+                await this.storeJwt(tokenData.jwt);
+              }
+              console.log("\n⚠️  New device detected — device confirmation required!");
+              console.log("─────────────────────────────────────────────────────");
+              console.log("A confirmation code has been sent to your email.");
+              console.log("You must confirm this device in your browser to complete login.");
+              console.log("\nPlease check the browser window you just used to approve the CLI session.");
+              console.log("Enter the email code there to confirm this device.");
+              console.log("\nAlternatively, visit your settings page:");
+              console.log(`  ${process.env.KNOWHOW_FRONTEND_URL || "https://knowhow.tyvm.ai"}/settings?tab=security`);
+              console.log("─────────────────────────────────────────────────────\n");
+
+              // Wait for the user to confirm the device — poll /api/users/me until
+              // the session becomes ACTIVE (device confirmed) or we time out.
+              await this.waitForDeviceConfirmation(tokenData.jwt);
+              return;
+            }
+
+            await this.storeJwt(tokenData.jwt);
             return;
           } else if (status.status.toLowerCase() === "denied") {
             throw new BrowserLoginError(
@@ -146,7 +172,8 @@ export class BrowserLoginService {
     try {
       const response = await http.post<CreateSessionResponse>(
         `${this.baseUrl}/api/cli-login/session`,
-        {}
+        {},
+        { headers: { "User-Agent": getCliUserAgent() } }
       );
       return response.data;
     } catch (error) {
@@ -188,6 +215,83 @@ export class BrowserLoginService {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  /**
+   * Poll /api/users/me with the pending JWT until the device confirmation is
+   * completed (session becomes ACTIVE) or we time out (~10 minutes).
+   * Shows a spinner so the user knows the CLI is still waiting.
+   */
+  private async waitForDeviceConfirmation(jwt: string): Promise<void> {
+    const spinner = new Spinner();
+    spinner.start("Waiting for device confirmation");
+
+    let isCancelled = false;
+    const cancelHandler = () => {
+      isCancelled = true;
+      spinner.stop();
+      console.log("\n\nCancelled. Your token is stored — once you confirm the device, re-run your command.");
+      process.exit(0);
+    };
+    process.once("SIGINT", cancelHandler);
+
+    const maxAttempts = 120; // 10 minutes at 5-second intervals
+    let attempt = 0;
+
+    while (attempt < maxAttempts) {
+      attempt++;
+
+      // Sleep in small increments so SIGINT can be checked more responsively
+      for (let i = 0; i < 10; i++) {
+        await this.sleep(500);
+        if (isCancelled) return;
+      }
+
+      try {
+        const response = await http.get(`${this.baseUrl}/api/users/me`, {
+          headers: { Authorization: `Bearer ${jwt}` },
+          timeout: 10000,
+        });
+
+        if (response.status === 200) {
+          // Device confirmed — session is now ACTIVE
+          spinner.stop();
+          process.removeListener("SIGINT", cancelHandler);
+          console.log("✅ Device confirmed! You are now logged in.");
+          return;
+        }
+      } catch (error) {
+        if (http.isHttpError(error)) {
+          if (error.status === 403) {
+            // Still pending — keep waiting
+            continue;
+          }
+          if (error.status === 401) {
+            // 401 can mean:
+            // - Session not found yet (timing issue, check-device may not have run)
+            // - Session is PENDING_DEVICE_CONFIRMATION (some backend versions return 401)
+            // - Token was actually revoked/expired
+            // Keep polling for the first ~5 attempts before giving up, to handle timing issues.
+            if (attempt >= 10) {
+              spinner.stop();
+              process.removeListener("SIGINT", cancelHandler);
+              throw new BrowserLoginError(
+                "Token expired or revoked during device confirmation. Please run 'knowhow login' again.",
+                "TOKEN_EXPIRED"
+              );
+            }
+            continue;
+          }
+        }
+      }
+    }
+
+    spinner.stop();
+    process.removeListener("SIGINT", cancelHandler);
+    console.log("\n⏰ Timed out waiting for device confirmation.");
+    console.log("Your token is stored — once you confirm the device at:");
+    console.log(`  ${process.env.KNOWHOW_FRONTEND_URL || "https://knowhow.tyvm.ai"}/settings?tab=security`);
+    console.log("you can re-run your command and it will work.\n");
+  }
+
   /**
    * Set up signal handlers for graceful shutdown
    */
@@ -201,6 +305,28 @@ export class BrowserLoginService {
   }
 }
 
+/**
+ * Build a descriptive User-Agent string for CLI sessions so they show up
+ * with meaningful device info in the sessions UI (e.g. "Knowhow CLI on macOS").
+ */
+export function getCliUserAgent(): string {
+  let cliVersion = "unknown";
+  try {
+    // __dirname is ts_build/src/auth/ at runtime, so go up 3 levels to package root
+    const pkgPath = path.resolve(__dirname, "../../../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    cliVersion = pkg.version ?? "unknown";
+  } catch {
+    // ignore — version is cosmetic
+  }
+  const platform = os.platform();
+  const osName =
+    platform === "darwin" ? "macOS" :
+    platform === "win32" ? "Windows" :
+    platform === "linux" ? "Linux" : platform;
+  return `Knowhow CLI/${cliVersion} (${osName})`;
+}
+
 /**
  * Utility function to open a URL in the default browser across different platforms
  */

package/src/chat/CliChatService.ts

@@ -216,12 +216,20 @@ export class CliChatService implements ChatService {
       } else {
         // Input starts with "/" but no matching command found - warn the user
         const availableCommands = this.getCommandsForActiveModes();
-        console.log(
-          `Unknown command "/${commandName}". Available commands: ${availableCommands
-            .map((cmd) => `/${cmd.name}`)
-            .join(", ")}`
-        );
-        return true;
+        // If the input looks like a filepath (contains path separators or file extensions),
+        // don't treat it as a failed command - let it fall through to modules
+        const looksLikeFilepath =
+          commandName.includes("/") ||
+          commandName.includes(".") ||
+          commandName.includes("\\");
+        if (!looksLikeFilepath) {
+          console.log(
+            `Unknown command "/${commandName}". Available commands: ${availableCommands
+              .map((cmd) => `/${cmd.name}`)
+              .join(", ")}`
+          );
+          return true;
+        }
       }
     }
 

package/src/chat/modules/AgentModule.ts

@@ -756,10 +756,12 @@ export class AgentModule extends BaseChatModule {
         ),
       ];
 
+      const customVariables = new CustomVariables(agent.tools);
+
       agent.messageProcessor.setProcessors("pre_call", [
         new Base64ImageProcessor(agent.tools).createProcessor(),
         ...caching,
-        new CustomVariables(agent.tools).createProcessor(),
+        customVariables.createProcessor(),
       ]);
 
       agent.messageProcessor.setProcessors("post_call", [
@@ -770,6 +772,7 @@ export class AgentModule extends BaseChatModule {
       agent.messageProcessor.setProcessors("post_tools", [
         new Base64ImageProcessor(agent.tools).createProcessor(),
         ...caching,
+        customVariables.createRepetitionHintProcessor(),
       ]);
 
       // Set up event listeners

package/src/chat/modules/ClipboardImageModule.ts

@@ -0,0 +1,136 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { ChatModule, ChatCommand, ChatMode, ChatContext } from "../types";
+import { CliChatService } from "../CliChatService";
+
+const execAsync = promisify(exec);
+
+/**
+ * Attempts to capture an image from the system clipboard and save it to a temp file.
+ * Returns the filepath if successful, or null if the clipboard has no image.
+ */
+export async function captureClipboardImage(): Promise<string | null> {
+  const tmpFile = path.join(os.tmpdir(), `knowhow-clipboard-${Date.now()}.png`);
+
+  const platform = process.platform;
+
+  try {
+    if (platform === "darwin") {
+      // macOS: use pngpaste if available, fall back to osascript
+      try {
+        await execAsync(`pngpaste "${tmpFile}"`);
+        if (fs.existsSync(tmpFile)) return tmpFile;
+      } catch {
+        // pngpaste not available or no image in clipboard, try osascript
+        const script = `
+          tell application "System Events"
+            set theImage to the clipboard as «class PNGf»
+            set fileRef to open for access POSIX file "${tmpFile}" with write permission
+            write theImage to fileRef
+            close access fileRef
+          end tell
+        `;
+        try {
+          await execAsync(`osascript -e '${script.replace(/'/g, "'\\''")}'`);
+          if (fs.existsSync(tmpFile)) return tmpFile;
+        } catch {
+          return null;
+        }
+      }
+    } else if (platform === "linux") {
+      // Linux: try xclip first, then xsel
+      try {
+        await execAsync(`xclip -selection clipboard -t image/png -o > "${tmpFile}"`);
+        if (fs.existsSync(tmpFile) && fs.statSync(tmpFile).size > 0) return tmpFile;
+      } catch {
+        try {
+          await execAsync(`xsel --clipboard --output > "${tmpFile}"`);
+          if (fs.existsSync(tmpFile) && fs.statSync(tmpFile).size > 0) return tmpFile;
+        } catch {
+          return null;
+        }
+      }
+    } else if (platform === "win32") {
+      // Windows: use PowerShell
+      const ps = `
+        Add-Type -AssemblyName System.Windows.Forms
+        $img = [System.Windows.Forms.Clipboard]::GetImage()
+        if ($img -ne $null) {
+          $img.Save('${tmpFile.replace(/\\/g, "\\\\")}')
+          Write-Output 'saved'
+        } else {
+          Write-Output 'no image'
+        }
+      `;
+      const { stdout } = await execAsync(`powershell -Command "${ps.replace(/"/g, '\\"')}"`);
+      if (stdout.trim() === "saved" && fs.existsSync(tmpFile)) return tmpFile;
+    }
+  } catch {
+    // Silently fail - clipboard doesn't contain an image
+  }
+
+  // Clean up empty file if created
+  try {
+    if (fs.existsSync(tmpFile) && fs.statSync(tmpFile).size === 0) {
+      fs.unlinkSync(tmpFile);
+    }
+  } catch { /* ignore */ }
+
+  return null;
+}
+
+export class ClipboardImageModule implements ChatModule {
+  name = "clipboard-image";
+  description = "Handles clipboard image paste detection and capture";
+  commands: ChatCommand[] = [];
+  modes: ChatMode[] = [];
+
+  getCommands(): ChatCommand[] {
+    return [
+      {
+        name: "paste",
+        description: "Capture image from clipboard and send to agent",
+        handler: this.handlePasteCommand.bind(this),
+      },
+    ];
+  }
+
+  getModes(): ChatMode[] {
+    return [];
+  }
+
+  async initialize(chatService: CliChatService): Promise<void> {
+    // Register /paste command
+    chatService.registerCommand({
+      name: "paste",
+      description: "Capture image from clipboard and send to agent",
+      handler: this.handlePasteCommand.bind(this),
+    });
+
+  }
+
+  private async handlePasteCommand(args: string[]): Promise<{ handled: boolean; contents?: string }> {
+    console.log("🔍 Checking clipboard for image...");
+    const filepath = await captureClipboardImage();
+
+    if (!filepath) {
+      console.log("No image found in clipboard. Copy an image first, then use /paste.");
+      return { handled: true };
+    }
+
+    console.log(`📋 Image captured: ${filepath}`);
+
+    // Return as not-handled so the filepath flows through to modules (AgentModule)
+    return { handled: false, contents: filepath };
+  }
+
+  async handleInput(input: string, context: ChatContext): Promise<boolean> {
+    return false; // This module only handles commands
+  }
+
+  async cleanup(): Promise<void> {
+  }
+}

package/src/chat/modules/InternalChatModule.ts

@@ -12,8 +12,10 @@ import { ShellCommandModule } from "./ShellCommandModule";
 import { RendererModule } from "./RendererModule";
 import { SessionsModule } from "./SessionsModule";
 import { RemoteSyncModule } from "./RemoteSyncModule";
+import { ClipboardImageModule } from "./ClipboardImageModule";
 
 export class InternalChatModule implements ChatModule {
+  private clipboardImageModule = new ClipboardImageModule();
   private chatService?: CliChatService;
   name = "internal";
   description = "Internal chat module aggregating all functionality";
@@ -57,6 +59,7 @@ export class InternalChatModule implements ChatModule {
     await this.customCommandsModule.initialize(chatService);
     await this.remoteSyncModule.initialize(chatService);
     await this.shellCommandModule.initialize(chatService);
+    await this.clipboardImageModule.initialize(chatService);
     
     // Register our own commands (exit and multi) - not duplicated by BaseChatModule
     chatService.registerCommand({

package/src/chat/modules/RendererModule.ts

@@ -6,6 +6,7 @@ import { ChatCommand, ChatMode, ChatContext, ChatService } from "../types";
 import { loadRenderer } from "../renderer/loadRenderer";
 import { ConsoleRenderer } from "../renderer";
 import { AgentModule } from "./AgentModule";
+import { getConfig, updateConfig } from "../../config";
 
 const BUILTIN_RENDERERS = ["basic", "compact", "fancy"];
 
@@ -27,10 +28,25 @@ export class RendererModule extends BaseChatModule {
   async initialize(service: ChatService): Promise<void> {
     await super.initialize(service);
 
-    // Initialize context.renderer with a default ConsoleRenderer if not already set
+    // Initialize context.renderer from config or default to ConsoleRenderer
     const context = service.getContext();
     if (!context.renderer) {
-      service.setContext({ renderer: new ConsoleRenderer() });
+      try {
+        const config = await getConfig();
+        const savedName = config.chat?.renderer;
+        if (savedName && savedName !== "basic") {
+          const savedRenderer = await loadRenderer(savedName);
+          this.currentRendererName = savedName;
+          service.setContext({ renderer: savedRenderer });
+        } else {
+          service.setContext({ renderer: new ConsoleRenderer() });
+          if (savedName === "basic" || !savedName) {
+            this.currentRendererName = "basic";
+          }
+        }
+      } catch {
+        service.setContext({ renderer: new ConsoleRenderer() });
+      }
     }
   }
 
@@ -85,6 +101,18 @@ export class RendererModule extends BaseChatModule {
       this.chatService?.setContext({ renderer: newRenderer });
       this.currentRendererName = specifier;
 
+      // Persist renderer preference to config
+      try {
+        const config = await getConfig();
+        config.chat = {
+          ...config.chat,
+          renderer: specifier,
+        };
+        await updateConfig(config);
+      } catch (saveErr: any) {
+        console.warn(`⚠️  Could not save renderer preference: ${saveErr.message}`);
+      }
+
       // Rewire agent rendering event listeners to the new renderer so live
       // events are forwarded correctly even mid-session.
       // This works because wireAgentRendering() always reads `this.renderer`