@tyvm/knowhow 0.0.83 → 0.0.84

package/src/chat/renderer/loadRenderer.ts

@@ -0,0 +1,314 @@
+/**
+ * Renderer Loader - Dynamically loads a custom renderer from an npm package or local file.
+ *
+ * Supports:
+ *  - built-in names:  "basic" | "fancy" | "compact"
+ *  - npm packages:   "@scope/package" or "my-renderer-package"
+ *  - local JS files: "./my-renderer.js" or "/absolute/path/renderer.js"
+ *  - local TS files: "./my-renderer.ts" (compiled on-the-fly via tsx/ts-node if available)
+ */
+
+import path from "path";
+import fs from "fs";
+import { AgentRenderer } from "./types";
+import { ConsoleRenderer } from "./ConsoleRenderer";
+import { FancyRenderer } from "./FancyRenderer";
+import { CompactRenderer } from "./CompactRenderer";
+
+/** Built-in renderer names that ship with knowhow */
+const BUILTIN_RENDERERS: Record<string, () => AgentRenderer> = {
+  basic: () => new ConsoleRenderer(),
+  fancy: () => new FancyRenderer(),
+  compact: () => new CompactRenderer(),
+};
+
+/**
+ * Attempt to transpile + load a TypeScript file as a module.
+ * Falls back gracefully if tsx / ts-node are unavailable.
+ */
+async function loadTsFile(filePath: string): Promise<any> {
+  // Try using jiti (another popular TS loader)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const jiti = require("jiti");
+    const loader = typeof jiti === "function" ? jiti : jiti.default;
+    return loader(filePath, { interopDefault: true })(filePath);
+  } catch (_) {}
+
+  // Try ts-node
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require("ts-node/register");
+    return require(filePath); // eslint-disable-line @typescript-eslint/no-var-requires
+  } catch (_) {}
+
+  // Last resort: try esbuild-register
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { register } = require("esbuild-register/dist/node");
+    const { unregister } = register();
+    const mod = require(filePath);
+    unregister();
+    return mod;
+  } catch (_) {}
+
+  throw new Error(
+    `Cannot load TypeScript file "${filePath}". Install tsx, jiti, ts-node, or esbuild-register:\n` +
+      `  npm install -g tsx\n  or  npm install -g ts-node`
+  );
+}
+
+/**
+ * Load a renderer from a specifier string.
+ *
+ * The loaded module must export either:
+ *   - A default export that is an AgentRenderer instance, OR
+ *   - A named export `createRenderer` function that returns an AgentRenderer, OR
+ *   - A named export `renderer` that is an AgentRenderer instance
+ *
+ * @param specifier - npm package name or file path (relative paths resolved from cwd)
+ * @returns An AgentRenderer instance
+ */
+export async function loadRenderer(specifier: string): Promise<AgentRenderer> {
+  // Check for built-in renderer names first
+  const builtin = BUILTIN_RENDERERS[specifier.toLowerCase()];
+  if (builtin) {
+    return builtin();
+  }
+
+  let mod: any;
+
+  const isLocalPath =
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith("/");
+
+  if (isLocalPath) {
+    const resolved = path.resolve(process.cwd(), specifier);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Renderer file not found: ${resolved}`);
+    }
+
+    if (resolved.endsWith(".ts")) {
+      mod = await loadTsFile(resolved);
+    } else {
+      // JS or JSON
+      mod = await import(resolved);
+    }
+  } else {
+    // npm package
+    try {
+      mod = await import(specifier);
+    } catch (err: any) {
+      throw new Error(
+        `Failed to load renderer package "${specifier}": ${err.message}\n` +
+          `Make sure it is installed: npm install -g ${specifier}`
+      );
+    }
+  }
+
+  // Resolve the renderer from the module exports
+  if (mod?.default && typeof mod.default.render === "function") {
+    return mod.default as AgentRenderer;
+  }
+
+  if (typeof mod?.createRenderer === "function") {
+    return mod.createRenderer() as AgentRenderer;
+  }
+
+  if (mod?.renderer && typeof mod.renderer.render === "function") {
+    return mod.renderer as AgentRenderer;
+  }
+
+  // Check the default export might be a class
+  if (mod?.default && typeof mod.default === "function") {
+    try {
+      const instance = new mod.default();
+      if (typeof instance.render === "function") {
+        return instance as AgentRenderer;
+      }
+    } catch (_) {}
+  }
+
+  // Check named exports for a class with "Renderer" in name
+  for (const key of Object.keys(mod || {})) {
+    if (key.toLowerCase().includes("renderer") && typeof mod[key] === "function") {
+      try {
+        const instance = new mod[key]();
+        if (typeof instance.render === "function") {
+          return instance as AgentRenderer;
+        }
+      } catch (_) {}
+    }
+  }
+
+  throw new Error(
+    `Renderer module "${specifier}" does not export a valid AgentRenderer.\n` +
+      `Expected one of:\n` +
+      `  - default export: AgentRenderer instance\n` +
+      `  - default export: AgentRenderer class\n` +
+      `  - named export "createRenderer": () => AgentRenderer\n` +
+      `  - named export "renderer": AgentRenderer instance\n` +
+      `  - named export "SomethingRenderer": AgentRenderer class`
+  );
+}
+
+/**
+ * Load a root chat module from a specifier string.
+ *
+ * The module must export either:
+ *   - A default export that is a ChatModule class or instance
+ *   - A named export "createModule" function
+ *   - A named export with "Module" in the name
+ */
+export async function loadRootModule(specifier: string): Promise<any> {
+  let mod: any;
+
+  const isLocalPath =
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith("/");
+
+  if (isLocalPath) {
+    const resolved = path.resolve(process.cwd(), specifier);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Root module file not found: ${resolved}`);
+    }
+
+    if (resolved.endsWith(".ts")) {
+      mod = await loadTsFile(resolved);
+    } else {
+      mod = await import(resolved);
+    }
+  } else {
+    try {
+      mod = await import(specifier);
+    } catch (err: any) {
+      throw new Error(
+        `Failed to load root module package "${specifier}": ${err.message}`
+      );
+    }
+  }
+
+  // Try default export as instance
+  if (mod?.default && typeof mod.default.initialize === "function") {
+    return mod.default;
+  }
+
+  // Try default export as class
+  if (mod?.default && typeof mod.default === "function") {
+    try {
+      const instance = new mod.default();
+      if (typeof instance.initialize === "function") {
+        return instance;
+      }
+    } catch (_) {}
+  }
+
+  // Try createModule factory
+  if (typeof mod?.createModule === "function") {
+    return mod.createModule();
+  }
+
+  // Try named exports with "Module" in name
+  for (const key of Object.keys(mod || {})) {
+    if (key.toLowerCase().includes("module") && typeof mod[key] === "function") {
+      try {
+        const instance = new mod[key]();
+        if (typeof instance.initialize === "function") {
+          return instance;
+        }
+      } catch (_) {}
+    }
+  }
+
+  throw new Error(
+    `Root module "${specifier}" does not export a valid ChatModule.\n` +
+      `Expected a class or instance with an "initialize(chatService)" method.`
+  );
+}
+
+/**
+ * Load an additional chat module (not the root module) from a specifier string.
+ *
+ * The module must export either:
+ *   - A default export that is a ChatModule class or instance
+ *   - A named export "createModule" function that returns a ChatModule
+ *   - A named export with "Module" in the name (class or instance)
+ *
+ * @param specifier - npm package name or file path (relative paths resolved from cwd)
+ * @returns An instantiated ChatModule (not yet initialized)
+ */
+export async function loadChatModule(specifier: string): Promise<any> {
+  let mod: any;
+
+  const isLocalPath =
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith("/");
+
+  if (isLocalPath) {
+    const resolved = path.resolve(process.cwd(), specifier);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Chat module file not found: ${resolved}`);
+    }
+
+    if (resolved.endsWith(".ts")) {
+      mod = await loadTsFile(resolved);
+    } else {
+      mod = await import(resolved);
+    }
+  } else {
+    try {
+      mod = await import(specifier);
+    } catch (err: any) {
+      throw new Error(
+        `Failed to load chat module package "${specifier}": ${err.message}`
+      );
+    }
+  }
+
+  // Try default export as instance (already has initialize)
+  if (mod?.default && typeof mod.default.initialize === "function") {
+    return mod.default;
+  }
+
+  // Try default export as class
+  if (mod?.default && typeof mod.default === "function") {
+    try {
+      const instance = new mod.default();
+      if (typeof instance.initialize === "function") {
+        return instance;
+      }
+    } catch (_) {}
+  }
+
+  // Try createModule factory
+  if (typeof mod?.createModule === "function") {
+    return mod.createModule();
+  }
+
+  // Try named exports with "Module" in name
+  for (const key of Object.keys(mod || {})) {
+    if (key.toLowerCase().includes("module") && typeof mod[key] === "function") {
+      try {
+        const instance = new mod[key]();
+        if (typeof instance.initialize === "function") {
+          return instance;
+        }
+      } catch (_) {}
+    }
+  }
+
+  throw new Error(
+    `Chat module "${specifier}" does not export a valid ChatModule.\n` +
+      `Expected a class or instance with an "initialize(chatService)" method.\n` +
+      `Supported export patterns:\n` +
+      `  - default export: ChatModule instance or class\n` +
+      `  - named export "createModule": () => ChatModule\n` +
+      `  - named export "SomethingModule": ChatModule class`
+  );
+}

package/src/chat/renderer/messagesToRenderEvents.ts

@@ -0,0 +1,96 @@
+/**
+ * Utility: Convert OpenAI-format Message[] threads into RenderEvent[] for the renderer.
+ * Shared by SyncedAgentWatcher implementations and the /logs command.
+ */
+
+import { RenderEvent } from "../../chat/renderer/types";
+
+export interface Message {
+  role: "assistant" | "user" | "tool" | "system";
+  content?: any;
+  tool_calls?: Array<{
+    id: string;
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+  name?: string;
+  tool_call_id?: string;
+}
+
+export function messagesToRenderEvents(
+  messages: Message[],
+  taskId: string,
+  agentName: string
+): RenderEvent[] {
+  const events: RenderEvent[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === "assistant") {
+      if (typeof msg.content === "string" && msg.content) {
+        events.push({
+          type: "agentMessage",
+          taskId,
+          agentName,
+          message: msg.content,
+          role: "assistant",
+        });
+      }
+      if (msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+          events.push({
+            type: "toolCall",
+            taskId,
+            agentName,
+            toolCall: {
+              id: tc.id,
+              function: {
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+              },
+            },
+          });
+        }
+      }
+    } else if (msg.role === "tool") {
+      const content =
+        typeof msg.content === "string"
+          ? msg.content
+          : JSON.stringify(msg.content);
+      events.push({
+        type: "toolResult",
+        taskId,
+        agentName,
+        toolCall: { function: { name: msg.name || "unknown", arguments: "" } },
+        result: content,
+      });
+    } else if (msg.role === "user") {
+      const content =
+        typeof msg.content === "string"
+          ? msg.content
+          : Array.isArray(msg.content)
+          ? msg.content
+              .filter((c: any) => c.type === "text")
+              .map((c: any) => c.text)
+              .join("\n")
+          : String(msg.content ?? "");
+      // Skip workflow messages — these are internal agent control messages
+      // injected as user-role messages and should not be rendered to the user
+      if (content.trim().startsWith("<Workflow>") || /<Workflow>/i.test(content)) {
+        continue;
+      }
+      if (content) {
+        events.push({
+          type: "agentMessage",
+          taskId,
+          agentName,
+          message: content,
+          role: "user",
+        });
+      }
+    }
+  }
+
+  return events;
+}

package/src/chat/renderer/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Renderer interfaces for CLI agent output
+ */
+
+export interface LogEvent {
+  taskId: string;
+  agentName: string;
+  message: string;
+  level: "info" | "warn" | "error";
+  timestamp: number;
+}
+
+export interface ToolCall {
+  id?: string;
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface ToolCallEvent {
+  taskId: string;
+  agentName: string;
+  toolCall: ToolCall;
+}
+
+export interface ToolResultEvent {
+  taskId: string;
+  agentName: string;
+  toolCall: ToolCall;
+  result: any;
+}
+
+export interface AgentMessageEvent {
+  taskId: string;
+  agentName: string;
+  message: string;
+  role: "assistant" | "user";
+}
+
+export interface AgentDoneEvent {
+  taskId: string;
+  agentName: string;
+  output: string;
+  totalCost: number;
+}
+
+export interface AgentStatusEvent {
+  taskId: string;
+  agentName: string;
+  statusMessage: string;
+  details: {
+    totalCostUsd: number;
+    elapsedMs: number;
+    remainingTimeMs?: number;
+    remainingTurns?: number;
+    remainingBudget?: number;
+  };
+  timestamp: number;
+}
+
+export type RenderEvent =
+  | ({ type: "log" } & LogEvent)
+  | ({ type: "agentStatus" } & AgentStatusEvent)
+  | ({ type: "toolCall" } & ToolCallEvent)
+  | ({ type: "toolResult" } & ToolResultEvent)
+  | ({ type: "agentMessage" } & AgentMessageEvent)
+  | ({ type: "agentDone" } & AgentDoneEvent);
+
+export interface AgentRenderer {
+  onLog(handler: (event: LogEvent) => void): void;
+  onAgentStatus(handler: (event: AgentStatusEvent) => void): void;
+  onToolCall(handler: (event: ToolCallEvent) => void): void;
+  onToolResult(handler: (event: ToolResultEvent) => void): void;
+  onAgentMessage(handler: (event: AgentMessageEvent) => void): void;
+  onAgentDone(handler: (event: AgentDoneEvent) => void): void;
+  render(event: RenderEvent): void;
+
+  /** Set the currently active agent task ID - only events for this task are shown */
+  setActiveTaskId(taskId: string | undefined): void;
+  getActiveTaskId(): string | undefined;
+
+  /**
+   * Replay the last N render events (used by /logs command).
+   * If count is not provided, shows last 10.
+   */
+  logMessages(events: RenderEvent[], count?: number): void;
+}

package/src/chat/types.ts

@@ -4,11 +4,13 @@
 import { ChatInteraction, Config } from "../types";
 import { BaseAgent } from "../agents/base/base";
 import { ToolsService } from "src/services";
+import { AgentRenderer } from "./renderer/types";
 
 export interface ChatContext {
   debugMode?: boolean;
   agentMode?: boolean;
   currentAgent?: string;
+  promptText?: string;
   searchMode?: boolean;
   voiceMode?: boolean;
   multilineMode?: boolean;
@@ -17,6 +19,8 @@ export interface ChatContext {
   inputMethod?: InputMethod;
   selectedAgent?: BaseAgent;
   plugins: string[];
+  activeAgentTaskId?: string;
+  renderer?: AgentRenderer;
 
   [key: string]: any;
 }
@@ -25,6 +29,7 @@ export interface ChatMode {
   name: string;
   description: string;
   active: boolean;
+  promptText?: string | (() => string);
 }
 
 export interface CommandResult {

package/src/chat.ts

@@ -2,11 +2,24 @@
 
 /**
  * New Modular Chat Interface - Simplified and cleaner than original chat.ts
+ *
+ * Supports custom renderers and root modules via .knowhow/knowhow.json:
+ *
+ * ```json
+ * {
+ *   "chat": {
+ *     "renderer": "./my-renderer.ts",       // local TS/JS file or npm package
+ *     "rootModule": "./my-module.ts"        // local TS/JS file or npm package
+ *   }
+ * }
+ * ```
  */
 
 import { CliChatService } from "./chat/CliChatService.js";
 import { InternalChatModule } from "./chat/modules/InternalChatModule.js";
 import { getConfig } from "./config.js";
+import { loadRenderer, loadRootModule, loadChatModule } from "./chat/renderer/loadRenderer.js";
+import { AgentModule } from "./chat/modules/AgentModule.js";
 
 async function main() {
   try {
@@ -39,11 +52,60 @@ async function main() {
     }
 
     // Create chat service with plugins
-    const chatService = new CliChatService(config.plugins.enabled);
+    const chatService = new CliChatService(config.plugins?.enabled ?? []);
 
-    // Load internal chat module (includes all core functionality)
-    const internalModule = new InternalChatModule();
-    await internalModule.initialize(chatService);
+    // ── Renderer ──────────────────────────────────────────────────────────────
+    // Load a custom renderer if configured, otherwise use the default
+    // ConsoleRenderer (already the default inside AgentModule).
+    const rendererSpecifier = config.chat?.renderer;
+    if (rendererSpecifier) {
+      try {
+        const customRenderer = await loadRenderer(rendererSpecifier);
+        // Inject the renderer into AgentModule via the chat service context
+        // AgentModule picks it up from context.renderer
+        chatService.setContext({ renderer: customRenderer });
+        console.log(`✓ Loaded custom renderer: ${rendererSpecifier}`);
+      } catch (err: any) {
+        console.warn(`⚠ Could not load renderer "${rendererSpecifier}": ${err.message}`);
+        console.warn("  Falling back to default ConsoleRenderer.");
+      }
+    }
+
+    // ── Root Module ───────────────────────────────────────────────────────────
+    // Allow swapping the root chat module entirely via config.
+    // The root module drives the whole CLI chat experience.
+    const rootModuleSpecifier = config.chat?.rootModule;
+    if (rootModuleSpecifier) {
+      try {
+        const customModule = await loadRootModule(rootModuleSpecifier);
+        await customModule.initialize(chatService);
+        console.log(`✓ Loaded custom root module: ${rootModuleSpecifier}`);
+      } catch (err: any) {
+        console.warn(`⚠ Could not load root module "${rootModuleSpecifier}": ${err.message}`);
+        console.warn("  Falling back to InternalChatModule.");
+        const internalModule = new InternalChatModule();
+        await internalModule.initialize(chatService);
+      }
+    } else {
+      // Default: use the internal module
+      const internalModule = new InternalChatModule();
+      await internalModule.initialize(chatService);
+    }
+
+    // ── Additional Chat Modules ────────────────────────────────────────────────
+    // Load any additional chat modules specified in config.chat.modules.
+    // These are loaded AFTER the root module so they can add commands/modes
+    // on top of whatever the root module provides.
+    const moduleSpecifiers = config.chat?.modules ?? [];
+    for (const specifier of moduleSpecifiers) {
+      try {
+        const chatModule = await loadChatModule(specifier);
+        await chatModule.initialize(chatService);
+        console.log(`✓ Loaded chat module: ${specifier}`);
+      } catch (err: any) {
+        console.warn(`⚠ Could not load chat module "${specifier}": ${err.message}`);
+      }
+    }
 
     // Start the chat loop
     await chatService.startChatLoop();
@@ -56,7 +118,9 @@ async function main() {
 // Check if this file is being run directly
 const isMainModule =
   (process.argv[1] && process.argv[1].endsWith("chat2.ts")) ||
-  (process.argv[1] && process.argv[1].endsWith("chat2.js"));
+  (process.argv[1] && process.argv[1].endsWith("chat2.js")) ||
+  (process.argv[1] && process.argv[1].endsWith("chat.ts")) ||
+  (process.argv[1] && process.argv[1].endsWith("chat.js"));
 
 if (isMainModule) {
   main().catch(console.error);