@tyvm/knowhow 0.0.83 → 0.0.85

package/src/services/SyncedAgentWatcher.ts

@@ -0,0 +1,397 @@
+/**
+ * SyncedAgentWatcher - Watch agents running in other processes or on knowhow-web
+ * and emit agent events as messages come in, decoupled from rendering.
+ */
+
+import { Message } from "../clients/types";
+import { EventService } from "./EventService";
+import * as fs from "fs";
+import * as fsPromises from "fs/promises";
+import * as path from "path";
+import { messagesToRenderEvents } from "../chat/renderer/messagesToRenderEvents";
+import { KnowhowSimpleClient } from "./KnowhowClient";
+
+export interface SyncedAgentWatcher {
+  /** Start watching for changes, emitting agent events */
+  startWatching(taskId: string): Promise<void>;
+  /** Stop watching */
+  stopWatching(): void;
+  /** The task ID being watched */
+  taskId: string;
+  /** The agent name being watched */
+  agentName: string;
+  /** Send a message to the remote agent */
+  sendMessage(message: string): Promise<void>;
+  /** Get current threads (for replaying history via /logs) */
+  getThreads(): Promise<any[][]>;
+  /** EventService that emits agent lifecycle events (toolCall, toolUsed, agentSay, threadUpdate, done) */
+  agentEvents: EventService;
+  /** Event type constants mirroring BaseAgent.eventTypes */
+  eventTypes: { done: string; toolCall: string; toolUsed: string; agentSay: string; threadUpdate: string };
+  /** Pause the remote agent */
+  pause(): Promise<void>;
+  /** Unpause/resume the remote agent */
+  unpause(): Promise<void>;
+  /** Kill/terminate the remote agent */
+  kill(): Promise<void>;
+}
+
+/**
+ * A minimal agent-like interface used by attachedAgentChatLoop.
+ * Both BaseAgent and WatcherBackedAgent implement this, allowing the
+ * single attachedAgentChatLoop to handle both local and remote agents.
+ */
+export interface AttachableAgent {
+  name: string;
+  agentEvents: EventService;
+  eventTypes: { done: string; toolCall?: string; toolUsed?: string; agentSay?: string };
+  getTotalCostUsd(): number;
+  pause(): void | Promise<void>;
+  unpause(): void | Promise<void>;
+  kill(): void | Promise<void>;
+  addPendingUserMessage(message: Message): void;
+}
+
+/**
+ * Adapts a SyncedAgentWatcher to the AttachableAgent interface so that
+ * attachedAgentChatLoop can drive both local agents and remote/watcher-backed
+ * agents through a single code path.
+ *
+ * - pause/unpause/kill delegate to the watcher
+ * - addPendingUserMessage calls watcher.sendMessage()
+ * - agentEvents and eventTypes are delegated to the watcher
+ * - "done" is emitted by the watcher when the remote agent completes
+ */
+export class WatcherBackedAgent implements AttachableAgent {
+  public name: string;
+  public agentEvents: EventService;
+  public eventTypes: { done: string };
+
+  constructor(public readonly watcher: SyncedAgentWatcher) {
+    this.name = watcher.agentName;
+    this.agentEvents = watcher.agentEvents;
+    this.eventTypes = watcher.eventTypes;
+  }
+
+  getTotalCostUsd(): number {
+    return 0;
+  }
+
+  async pause(): Promise<void> {
+    await this.watcher.pause();
+  }
+
+  async unpause(): Promise<void> {
+    await this.watcher.unpause();
+  }
+
+  async kill(): Promise<void> {
+    await this.watcher.kill();
+    // Signal the chat loop to exit
+    this.agentEvents.emit(this.eventTypes.done, "Agent killed");
+  }
+
+  addPendingUserMessage(message: Message): void {
+    // Fire-and-forget — errors are logged but not surfaced
+    const text = typeof message.content === "string" ? message.content : "";
+    this.watcher
+      .sendMessage(text)
+      .then(() => {
+        console.log(`📨 Message sent to ${this.name}`);
+      })
+      .catch((err) => {
+        console.error(`❌ Failed to send message to ${this.name}:`, err);
+      });
+  }
+}
+
+/**
+ * Watches an agent running in another process via the filesystem.
+ * Reads .knowhow/processes/agents/<taskId>/metadata.json for changes.
+ * Sends messages by writing to .knowhow/processes/agents/<taskId>/input.txt
+ */
+export class FsSyncedAgentWatcher implements SyncedAgentWatcher {
+  public taskId: string = "";
+  private taskPath: string = "";
+  private watcher: fs.FSWatcher | null = null;
+  private lastThreadLength: number = 0;
+  public agentName: string = "unknown";
+  private debounceTimer: NodeJS.Timeout | null = null;
+  public agentEvents = new EventService();
+  public eventTypes = {
+    done: "done",
+    toolCall: "tool:pre_call",
+    toolUsed: "tool:post_call",
+    agentSay: "agent:say",
+    threadUpdate: "thread_update",
+  };
+
+  async startWatching(taskId: string): Promise<void> {
+    this.taskId = taskId;
+    this.taskPath = path.join(".knowhow/processes/agents", taskId);
+
+    // Load initial state to track current thread length (for delta rendering)
+    const metadata = await this.readMetadata();
+    if (metadata) {
+      const threads: any[][] = metadata.threads || [];
+      const lastThread = threads[threads.length - 1] || [];
+      this.agentName = metadata.agentName || taskId;
+      this.lastThreadLength = lastThread.length;
+    }
+
+    // Watch the directory for metadata.json changes
+    try {
+      this.watcher = fs.watch(this.taskPath, (event, filename) => {
+        if (filename === "metadata.json" || filename === null) {
+          // Debounce rapid file writes
+          if (this.debounceTimer) clearTimeout(this.debounceTimer);
+          this.debounceTimer = setTimeout(() => {
+            this.onMetadataChanged().catch(() => {});
+          }, 200);
+        }
+      });
+    } catch (err: any) {
+      console.warn(`⚠️  Could not watch ${this.taskPath}: ${err.message}`);
+    }
+
+    console.log(`👁️  Watching fs-synced agent: ${taskId} (${this.agentName})`);
+    console.log(
+      `   Type /logs 20 to see recent messages, or type to send a message`
+    );
+  }
+
+  private async onMetadataChanged(): Promise<void> {
+    const metadata = await this.readMetadata();
+    if (!metadata?.threads) return;
+
+    const threads: any[][] = metadata.threads;
+    const lastThread = threads[threads.length - 1] || [];
+
+    // Only render NEW messages since last check
+    const newMessages = lastThread.slice(this.lastThreadLength);
+    if (newMessages.length > 0) {
+      const renderEvents = messagesToRenderEvents(
+        newMessages,
+        this.taskId,
+        this.agentName
+      );
+      for (const event of renderEvents) {
+        if (event.type === "toolCall") {
+          this.agentEvents.emit(this.eventTypes.toolCall, {
+            toolCall: (event as any).toolCall,
+          });
+        } else if (event.type === "toolResult") {
+          this.agentEvents.emit(this.eventTypes.toolUsed, {
+            toolCall: (event as any).toolCall,
+            functionResp: (event as any).result,
+          });
+        } else if (event.type === "agentMessage") {
+          this.agentEvents.emit(this.eventTypes.agentSay, {
+            message: (event as any).message,
+          });
+        }
+      }
+      this.agentEvents.emit(this.eventTypes.threadUpdate, lastThread);
+      this.lastThreadLength = lastThread.length;
+    }
+
+    // Emit done if the agent has completed and has a result
+    const status = metadata.status;
+    const result = metadata.result;
+    if ((status === "completed" || status === "killed") && result != null) {
+      this.stopWatching();
+      this.agentEvents.emit(this.eventTypes.done, result);
+    }
+  }
+
+  async sendMessage(message: string): Promise<void> {
+    const inputPath = path.join(this.taskPath, "input.txt");
+    await fsPromises.writeFile(inputPath, message, "utf8");
+  }
+
+  async getThreads(): Promise<any[][]> {
+    const metadata = await this.readMetadata();
+    return metadata?.threads || [];
+  }
+
+  stopWatching(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.watcher?.close();
+    this.watcher = null;
+    console.log(`🔌 Stopped watching agent: ${this.taskId}`);
+  }
+
+  async pause(): Promise<void> {
+    const statusPath = path.join(this.taskPath, "status.txt");
+    await fsPromises.writeFile(statusPath, "paused", "utf8");
+    console.log(`⏸️  Paused remote agent: ${this.taskId}`);
+  }
+
+  async unpause(): Promise<void> {
+    const statusPath = path.join(this.taskPath, "status.txt");
+    await fsPromises.writeFile(statusPath, "running", "utf8");
+    console.log(`▶️  Unpaused remote agent: ${this.taskId}`);
+  }
+
+  async kill(): Promise<void> {
+    const statusPath = path.join(this.taskPath, "status.txt");
+    await fsPromises.writeFile(statusPath, "killed", "utf8");
+    console.log(`🛑 Killed remote agent: ${this.taskId}`);
+  }
+
+  private async readMetadata(): Promise<any> {
+    try {
+      const metaPath = path.join(this.taskPath, "metadata.json");
+      const content = await fsPromises.readFile(metaPath, "utf8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Watches an agent running on Knowhow Web via polling the API.
+ * Polls GET /tasks/<taskId> every 3 seconds for thread updates.
+ * Sends messages via the client's sendMessageToAgent method.
+ */
+export class WebSyncedAgentWatcher implements SyncedAgentWatcher {
+  public taskId: string = "";
+  private client: KnowhowSimpleClient;
+  private pollInterval: NodeJS.Timeout | null = null;
+  private lastThreadLength: number = 0;
+  public agentName: string = "remote-agent";
+  private stopped: boolean = false;
+  public agentEvents = new EventService();
+  public eventTypes = {
+    done: "done",
+    toolCall: "tool:pre_call",
+    toolUsed: "tool:post_call",
+    agentSay: "agent:say",
+    threadUpdate: "thread_update",
+  };
+
+  constructor(client?: KnowhowSimpleClient) {
+    this.client = client || new KnowhowSimpleClient();
+  }
+
+  async startWatching(taskId: string): Promise<void> {
+    this.taskId = taskId;
+    this.stopped = false;
+
+    // Load initial state to track current thread length
+    try {
+      const details = await this.client.getTaskDetails(taskId);
+      const threads: any[][] = details?.data?.threads || [];
+      const lastThread = threads[threads.length - 1] || [];
+      this.agentName = "remote-agent";
+      this.lastThreadLength = lastThread.length;
+    } catch (err: any) {
+      console.warn(
+        `⚠️  Could not load initial state for task ${taskId}: ${err.message}`
+      );
+    }
+
+    // Poll every 3 seconds for updates
+    this.pollInterval = setInterval(async () => {
+      if (!this.stopped) {
+        await this.onPoll().catch(() => {});
+      }
+    }, 3000);
+
+    console.log(`🌐 Watching web-synced agent: ${taskId} (${this.agentName})`);
+    console.log(
+      `   Type /logs 20 to see recent messages, or type to send a message`
+    );
+  }
+
+  private async onPoll(): Promise<void> {
+    if (this.stopped) return;
+    try {
+      const details = await this.client.getTaskDetails(this.taskId);
+      const threads: any[][] = details?.data?.threads || [];
+      const lastThread = threads[threads.length - 1] || [];
+
+      const newMessages = lastThread.slice(this.lastThreadLength);
+      if (newMessages.length > 0) {
+        const renderEvents = messagesToRenderEvents(
+          newMessages,
+          this.taskId,
+          this.agentName
+        );
+        for (const event of renderEvents) {
+          if (event.type === "toolCall") {
+            this.agentEvents.emit(this.eventTypes.toolCall, {
+              toolCall: (event as any).toolCall,
+            });
+          } else if (event.type === "toolResult") {
+            this.agentEvents.emit(this.eventTypes.toolUsed, {
+              toolCall: (event as any).toolCall,
+              functionResp: (event as any).result,
+            });
+          } else if (event.type === "agentMessage") {
+            this.agentEvents.emit(this.eventTypes.agentSay, {
+              message: (event as any).message,
+            });
+          }
+        }
+        this.agentEvents.emit(this.eventTypes.threadUpdate, lastThread);
+        this.lastThreadLength = lastThread.length;
+      }
+
+      // Stop polling and emit done if task is complete with a result
+      const status = details?.data?.status;
+      const result = details?.data?.result;
+      if (status === "completed" || status === "killed") {
+        this.stopWatching();
+        if (result != null) {
+          this.agentEvents.emit(this.eventTypes.done, result);
+        } else {
+          console.log(`\n✅ Remote agent ${this.taskId} status: ${status} (no result)`);
+        }
+      }
+    } catch {
+      // Silently continue on poll errors
+    }
+  }
+
+  async sendMessage(message: string): Promise<void> {
+    await this.client.sendMessageToAgent(this.taskId, message);
+  }
+
+  async getThreads(): Promise<any[][]> {
+    try {
+      const details = await this.client.getTaskDetails(this.taskId);
+      return details?.data?.threads || [];
+    } catch {
+      return [];
+    }
+  }
+
+  stopWatching(): void {
+    this.stopped = true;
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = null;
+    }
+    console.log(`🔌 Stopped watching web agent: ${this.taskId}`);
+  }
+
+  async pause(): Promise<void> {
+    await this.client.pauseAgent(this.taskId);
+    console.log(`⏸️  Paused remote web agent: ${this.taskId}`);
+  }
+
+  async unpause(): Promise<void> {
+    await this.client.resumeAgent(this.taskId);
+    console.log(`▶️  Unpaused remote web agent: ${this.taskId}`);
+  }
+
+  async kill(): Promise<void> {
+    await this.client.killAgent(this.taskId);
+    console.log(`🛑 Killed remote web agent: ${this.taskId}`);
+  }
+}

package/src/services/SyncerService.ts

@@ -0,0 +1,147 @@
+/**
+ * SyncerService - Unified wrapper around AgentSyncFs and AgentSyncKnowhowWeb
+ * Hides complexity of choosing and managing sync backends.
+ */
+import { BaseAgent } from "../agents/base/base";
+import { AgentSyncFs } from "./AgentSyncFs";
+import { AgentSyncKnowhowWeb } from "./AgentSyncKnowhowWeb";
+
+export interface SyncerOptions {
+  taskId: string;
+  prompt: string;
+  /** If provided → use web sync (unless syncFs is set) */
+  messageId?: string;
+  /** Force fs sync even if messageId is provided */
+  syncFs?: boolean;
+  /** Use an existing Knowhow task ID instead of creating a new one */
+  existingKnowhowTaskId?: string;
+  /** Agent name to persist in metadata.json */
+  agentName?: string;
+}
+
+export interface AgentSyncer {
+  /** Set up sync for a new task. Returns the sync task ID */
+  createTask(options: SyncerOptions): Promise<string>;
+  /** Wire up event listeners on the agent */
+  setupAgentSync(agent: BaseAgent, taskId: string): Promise<void>;
+  /** Wait for all pending sync operations to complete */
+  waitForFinalization(): Promise<void>;
+  /** Reset state for next task */
+  reset(): void;
+  /** Whether this syncer is active (has been configured) */
+  isActive(): boolean;
+}
+
+/**
+ * SyncerService implements AgentSyncer by delegating to AgentSyncFs and/or AgentSyncKnowhowWeb.
+ *
+ * Decision logic:
+ *   - Always sets up AgentSyncFs (primary local syncer)
+ *   - If messageId is present AND syncFs is not forced AND no existingKnowhowTaskId → also sets up AgentSyncKnowhowWeb
+ */
+export class SyncerService implements AgentSyncer {
+  private fsSync: AgentSyncFs;
+  private webSync: AgentSyncKnowhowWeb;
+  private active: boolean = false;
+  private useWebSync: boolean = false;
+  private createdTaskId: string | undefined;
+
+  constructor() {
+    this.fsSync = new AgentSyncFs();
+    this.webSync = new AgentSyncKnowhowWeb();
+  }
+
+  /**
+   * Create sync task(s) and return the primary task ID.
+   * The returned ID is the local (fs) task ID.
+   */
+  async createTask(options: SyncerOptions): Promise<string> {
+    this.active = true;
+    this.useWebSync = false;
+
+    // Determine whether to use web sync
+    const shouldUseWebSync =
+      !!options.messageId &&
+      !options.syncFs &&
+      !options.existingKnowhowTaskId;
+
+    // Always create fs sync task first
+    console.log(
+      `📁 Using filesystem-based synchronization for task: ${options.taskId}`
+    );
+    const fsTaskId = await this.fsSync.createTask({
+      taskId: options.taskId,
+      prompt: options.prompt,
+      agentName: options.agentName,
+    });
+
+    // Optionally create web sync task
+    if (shouldUseWebSync) {
+      const knowhowTaskId = await this.webSync.createChatTask({
+        messageId: options.messageId,
+        prompt: options.prompt,
+      });
+
+      if (knowhowTaskId) {
+        this.useWebSync = true;
+        this.createdTaskId = knowhowTaskId;
+        console.log(`🌐 Web sync task created: ${knowhowTaskId}`);
+      }
+    }
+
+    return fsTaskId;
+  }
+
+  /**
+   * Wire up event listeners for all active sync backends.
+   * @param agent - the agent to sync
+   * @param taskId - the fs task ID (returned by createTask)
+   */
+  async setupAgentSync(agent: BaseAgent, taskId: string): Promise<void> {
+    await this.fsSync.setupAgentSync(agent, taskId);
+
+    if (this.useWebSync && this.createdTaskId) {
+      await this.webSync.setupAgentSync(agent, this.createdTaskId);
+    }
+  }
+
+  /**
+   * Wait for finalization across all active sync backends.
+   */
+  async waitForFinalization(): Promise<void> {
+    if (this.useWebSync) {
+      console.log("🎯 [SyncerService] Waiting for web sync finalization...");
+      await this.webSync.waitForFinalization();
+      console.log("🎯 [SyncerService] Web sync finalization complete");
+    }
+
+    console.log("🎯 [SyncerService] Waiting for fs sync finalization...");
+    await this.fsSync.waitForFinalization();
+    console.log("🎯 [SyncerService] Fs sync finalization complete");
+  }
+
+  /**
+   * Reset both sync backends for the next task.
+   */
+  reset(): void {
+    this.webSync.reset();
+    this.fsSync.reset();
+    this.active = false;
+    this.useWebSync = false;
+    this.createdTaskId = undefined;
+  }
+
+  /**
+   * Whether this syncer has been configured for a task.
+   */
+  isActive(): boolean {
+    return this.active;
+  }
+
+  /**
+   * Returns the Knowhow web task ID if one was created (for updating TaskInfo).
+   */
+  getCreatedWebTaskId(): string | undefined {
+    return this.useWebSync ? this.createdTaskId : undefined;
+  }
+}

package/src/services/index.ts

@@ -29,6 +29,8 @@ export * from "./AgentSyncKnowhowWeb";
 export * from "./AgentSyncFs";
 export * from "./SessionManager";
 export * from "./TaskRegistry";
+export * from "./SyncedAgentWatcher";
+export * from "./SyncerService";
 export { Clients } from "../clients";
 
 let Singletons = {} as {

package/src/services/modules/index.ts

@@ -1,4 +1,4 @@
-import { getConfig } from "../../config";
+import { getConfig, getGlobalConfig } from "../../config";
 import { KnowhowModule, ModuleContext } from "./types";
 import { ToolsService } from "../Tools";
 import { services } from "../";
@@ -25,9 +25,14 @@ export class ModulesService {
     const pluginService = context.Plugins;
     const clients = context.Clients;
 
-    const modules = config.modules || [];
+    // Load from global config (~/.knowhow/knowhow.json) first, then local config
+    const globalConfig = await getGlobalConfig();
+    const allModulePaths = [
+      ...(globalConfig.modules || []),
+      ...(config.modules || []),
+    ];
 
-    for (const modulePath of modules) {
+    for (const modulePath of allModulePaths) {
       const importedModule = require(modulePath) as KnowhowModule;
       await importedModule.init({ config, cwd: process.cwd() });
 
@@ -49,5 +54,11 @@ export class ModulesService {
         clients.registerModels(client.provider, client.models);
       }
     }
+
+    // Also load plugins directly from config's pluginPackages map
+    if (pluginService) {
+      await pluginService.loadPluginsFromConfig(config);
+      await pluginService.loadPluginsFromConfig(globalConfig);
+    }
   }
 }