@tyvm/knowhow 0.0.158 → 0.0.160

package/src/services/modules/index.ts

@@ -1,314 +0,0 @@
-import * as path from "path";
-import * as os from "os";
-import * as Module from "module";
-
-import { getConfig, getGlobalConfig } from "../../config";
-import { KnowhowModule, ModuleContext } from "./types";
-import { services } from "../";
-import { toUniqueArray } from "../../utils";
-
-/**
- * Module resolution search paths.
- *
- * A module's resolution order depends on WHICH config declared it:
- *
- * - Modules declared in the GLOBAL config should resolve against the global
- *   install's node_modules (~/.knowhow/node_modules) — i.e. what's installed
- *   alongside the global config. We still fall back to cwd paths as a last
- *   resort so a globally-declared module can still be found if it only exists
- *   locally.
- *
- * - Modules declared in the LOCAL config should resolve against the local
- *   project first (cwd/.knowhow/node_modules), then the global config's
- *   node_modules (~/.knowhow/node_modules), then cwd/node_modules.
- */
-function localResolvePaths(): string[] {
-  return [
-    path.join(process.cwd(), ".knowhow", "node_modules"),
-    path.join(os.homedir(), ".knowhow", "node_modules"),
-    path.join(process.cwd(), "node_modules"),
-  ];
-}
-
-function globalResolvePaths(): string[] {
-  return [
-    path.join(os.homedir(), ".knowhow", "node_modules"),
-    path.join(process.cwd(), ".knowhow", "node_modules"),
-    path.join(process.cwd(), "node_modules"),
-  ];
-}
-
-export class ModulesService {
-  private _loadedModules: {
-    modulePath: string;
-    resolvedPath: string;
-    module: KnowhowModule;
-    params: any;
-  }[] = [];
-
-  async getDefaultContext() {
-    return { ...services() };
-  }
-
-  async overrideDefaultContext(overrides: Partial<ModuleContext>) {
-    const defaultContext = await this.getDefaultContext();
-    return { ...defaultContext, ...overrides };
-  }
-
-  async loadModulesFrom(
-    config: { modules: string[] } & any,
-    context?: Partial<ModuleContext>,
-    resolvePaths: string[] = localResolvePaths()
-  ) {
-    // If no context provided, fall back to global singletons
-    if (!context) {
-      context = { ...(await this.getDefaultContext()) };
-    }
-
-    // Prepend the global knowhow install's own node_modules to Node's global module
-    // search paths so that locally-installed modules (loaded from .knowhow/node_modules)
-    // that depend on @tyvm/knowhow resolve to the current global version rather than
-    // a stale bundled copy.
-    const globalKnowhowNodeModules = path.join(__dirname, "../../../../node_modules");
-    const globalPaths = (Module as any).globalPaths as string[];
-    if (globalPaths && !globalPaths.includes(globalKnowhowNodeModules)) {
-      globalPaths.unshift(globalKnowhowNodeModules);
-    }
-
-    const allModulePaths = config.modules;
-
-    // `resolvePaths` (passed in by the caller) determines the search-path order.
-    // Global-config modules resolve against ~/.knowhow/node_modules first; local-config
-    // modules resolve against cwd/.knowhow/node_modules first. See localResolvePaths()
-    // and globalResolvePaths() above.
-
-    // Two-phase load:
-    //   Phase 1 (register): resolve + require EVERY module and run its optional
-    //     `register()`, which may (a) register CLI subcommands on Program and
-    //     (b) inject shared services into `context` (e.g. `ComputerUse`) so that
-    //     sibling/adapter modules loaded later can consume them.
-    //   Phase 2 (init): run every loaded module's `init()`, now that all
-    //     services registered during phase 1 are present. This lets, e.g., a
-    //     `-nutjs` adapter module register a driver against the base
-    //     computer-use service during phase 1, and the base module resolve the
-    //     best driver during phase 2.
-    const loadedModules: {
-      modulePath: string;
-      resolvedPath: string;
-      module: KnowhowModule;
-    }[] = [];
-
-    for (const modulePath of allModulePaths) {
-      // Build an ordered list of candidate resolutions for this module.
-      // Relative paths resolve to a single candidate (relative to cwd), while
-      // npm package names get one candidate per search path so we can fall
-      // back to the global install if a locally-symlinked (e.g. workspace dev)
-      // build fails to load (wrong Node ABI, broken build, etc.).
-      const candidates: string[] = [];
-      if (modulePath.startsWith(".")) {
-        candidates.push(path.resolve(process.cwd(), modulePath));
-      } else {
-        // For npm package names, resolve against each search path individually
-        // (in priority order) so each becomes its own fallback candidate.
-        for (const searchPath of resolvePaths) {
-          try {
-            const resolved = require.resolve(modulePath, {
-              paths: [searchPath],
-            });
-            if (!candidates.includes(resolved)) candidates.push(resolved);
-          } catch {
-            // this search path doesn't have the module — try the next one
-          }
-        }
-        // Finally, normal require resolution as a last resort.
-        try {
-          const resolved = require.resolve(modulePath);
-          if (!candidates.includes(resolved)) candidates.push(resolved);
-        } catch {
-          // ignore — will fall through to the bare name below
-        }
-        if (candidates.length === 0) candidates.push(modulePath);
-      }
-
-      // Try each candidate in order. Only if EVERY candidate fails to load do
-      // we surface an error — a failure on one candidate (e.g. a stale local
-      // workspace build) should silently fall back to the next (e.g. the
-      // global install).
-      let importedModule: KnowhowModule;
-      let loaded = false;
-      let selectedResolvedPath = modulePath;
-      const errors: { candidate: string; error: Error }[] = [];
-      for (const resolvedPath of candidates) {
-        try {
-          const rawModule = require(resolvedPath);
-          importedModule = (rawModule.default || rawModule) as KnowhowModule;
-          context.Events?.log(
-            "ModulesService",
-            `🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`
-          );
-          // Phase 1: register (optional). Injects services into `context` and
-          // registers CLI commands. Must be idempotent (may run in the early
-          // Program-only CLI phase AND the full-services phase).
-          if (typeof importedModule.register === "function") {
-            await importedModule.register({
-              config,
-              cwd: process.cwd(),
-              context: context as ModuleContext,
-            });
-          }
-          selectedResolvedPath = resolvedPath;
-          loaded = true;
-          break;
-        } catch (err: any) {
-          errors.push({ candidate: resolvedPath, error: err });
-          // try the next candidate
-        }
-      }
-
-      if (!loaded) {
-        // All candidates failed — report the last (most fully-resolved) error.
-        const last = errors[errors.length - 1];
-        const detail = last
-          ? `${last.error.message}`
-          : "no resolvable module found";
-        process.stderr.write(
-          `\n⚠️  Failed to load module "${modulePath}": ${detail}\n` +
-          `   Tried: ${candidates.join(", ") || "(none)"}\n` +
-          `   Run "knowhow modules setup --global" or "knowhow modules install ${modulePath} --global" to fix this.\n\n`
-        );
-        continue;
-      }
-      loadedModules.push({
-        modulePath,
-        resolvedPath: selectedResolvedPath,
-        module: importedModule,
-      });
-    }
-
-    // Phase 2: init every successfully-loaded module now that all `register`
-    // phases have run and injected their services into `context`.
-    for (const { modulePath, resolvedPath, module: importedModule } of loadedModules) {
-      const initParams = { config, cwd: process.cwd(), context: context as ModuleContext };
-      try {
-        await importedModule.init({
-          config,
-          cwd: process.cwd(),
-          context: context as ModuleContext,
-        });
-        context.Events?.log(
-          "ModulesService",
-          `✅ Module initialized: ${modulePath} (tools: ${importedModule.tools.length}, agents: ${importedModule.agents.length}, plugins: ${importedModule.plugins.length}, clients: ${importedModule.clients.length})`
-        );
-      } catch (err: any) {
-        process.stderr.write(
-          `\n⚠️  Failed to init module "${modulePath}": ${err?.message || err}\n\n`
-        );
-        continue;
-      }
-      this._loadedModules.push({ modulePath, resolvedPath, module: importedModule, params: initParams });
-
-      context.Extensions?.removeOwner(modulePath);
-      for (const extension of importedModule.extensions ?? []) {
-        context.Extensions?.register(modulePath, extension);
-      }
-
-      // Only register tools/agents/plugins/clients if the relevant services
-      // are available in context (they may not be during early CLI command registration)
-      if (context.Agents) {
-        for (const agent of importedModule.agents) {
-          context.Agents.registerAgent(agent);
-        }
-      }
-
-      if (context.Tools) {
-        for (const tool of importedModule.tools) {
-          context.Tools.addTool(tool.definition);
-          context.Tools.setFunction(
-            tool.definition.function.name,
-            tool.handler
-          );
-        }
-      }
-
-      if (context.Plugins) {
-        for (const plugin of importedModule.plugins) {
-          context.Plugins.registerPlugin(
-            plugin.name,
-            new plugin.plugin(context as any)
-          );
-        }
-      }
-
-      if (context.Clients) {
-        for (const client of importedModule.clients) {
-          context.Clients.registerClient(client.provider, client.client);
-          context.Clients.registerModels(client.provider, client.models);
-        }
-      }
-    }
-  }
-
-  /**
-   * Call `destroy()` on every successfully-initialized module, in reverse
-   * initialization order (last-in, first-out). Errors are caught and logged
-   * so one broken module does not prevent others from cleaning up.
-   */
-  async destroyModules() {
-    const toDestroy = [...this._loadedModules].reverse();
-    // Clear first so repeated shutdown/reload attempts cannot destroy twice.
-    this._loadedModules = [];
-    for (const { modulePath, resolvedPath, module: mod, params } of toDestroy) {
-      params.context?.Extensions?.removeOwner(modulePath);
-      if (typeof mod.destroy === "function") {
-        try {
-          await mod.destroy(params);
-        } catch (err: any) {
-          process.stderr.write(
-            `\n⚠️  Error in module destroy "${modulePath}": ${err?.message || err}\n\n`
-          );
-        }
-      }
-      // Re-require the entry point so source/configuration changes are visible.
-      if (require.cache[resolvedPath]) {
-        delete require.cache[resolvedPath];
-      }
-    }
-  }
-
-  async loadModulesFromConfig(context?: ModuleContext) {
-    const config = await getConfig();
-
-    const globalConfig = await getGlobalConfig();
-
-    const globalModules = toUniqueArray(globalConfig.modules || []);
-    // Local modules already loaded globally shouldn't be loaded again (a module
-    // that adds a CLI command would throw "already have command"). De-dupe local
-    // against global.
-    const localModules = toUniqueArray(config.modules || []).filter(
-      (m) => !globalModules.includes(m)
-    );
-
-    // Load global-config modules resolving against the global install's
-    // node_modules (~/.knowhow/node_modules) first.
-    // Pass a merged config so that keys defined in the global config (e.g.
-    // `tracing`) are visible to globally-declared modules during init().
-    // Local config keys take precedence so that local overrides still work.
-    if (globalModules.length > 0) {
-      await this.loadModulesFrom(
-        { ...globalConfig, ...config, modules: globalModules },
-        context,
-        globalResolvePaths()
-      );
-    }
-
-    // Load local-config modules resolving against the local project's
-    // node_modules (cwd/.knowhow/node_modules) first.
-    if (localModules.length > 0) {
-      await this.loadModulesFrom(
-        { ...config, modules: localModules },
-        context,
-        localResolvePaths()
-      );
-    }
-  }
-}

package/src/services/modules/types.ts

@@ -1,109 +0,0 @@
-import { Plugin, PluginContext } from "../../plugins/types";
-import { Command } from "commander";
-import { IAgent } from "../../agents/interface";
-import { Tool } from "../../clients/types";
-import { Config } from "../../types";
-import { GenericClient } from "../../clients/types";
-import { AgentService } from "../AgentService";
-import { EmbeddingsService } from "../EmbeddingsService";
-import { PluginService } from "../../plugins/plugins";
-import { AIClient } from "../../clients";
-import { ToolsService } from "../Tools";
-import { MediaProcessorService } from "../MediaProcessorService";
-import { TunnelHandler } from "@tyvm/knowhow-tunnel";
-import { EventService } from "../EventService";
-import { ConversionService } from "../conversion/ConversionService";
-import { BehaviorsService } from "../BehaviorsService";
-import { ComputerUseService } from "./computerUse";
-import { ExtensionsService, ModuleExtension } from "../ExtensionsService";
-
-import { TracingService as TracingServiceType } from "../TracingService";
-/*
- *
- * A a module should allow the dynamic composition of npm modules that are installed globally by referencing an array of config
- *
- * A module can add new commands to the chat loop, new tools, new agents, new plugins, new clients, new server features etc.
- *
- */
-export interface ModuleChatCommand {
-  name: string;
-  description: string;
-  handler: (ctx: any) => void;
-}
-
-export interface ModuleTool {
-  name: string;
-  handler: (...args: any[]) => any;
-  definition: Tool;
-}
-
-export type ModuleAgent = IAgent;
-
-export type PluginConstructor = new (context: PluginContext) => Plugin;
-export type ModulePlugin = { name: string; plugin: PluginConstructor };
-
-export type ModuleClient = {
-  client: GenericClient;
-  provider: string;
-  models: string[];
-};
-
-export type InitParams = {
-  config: Config;
-  cwd: string;
-  context?: ModuleContext;
-};
-
-export interface ModuleContext {
-  Agents: AgentService;
-  Embeddings: EmbeddingsService;
-  Plugins: PluginService;
-  Clients: AIClient;
-  Tools: ToolsService;
-  Events: EventService;
-  MediaProcessor?: MediaProcessorService;
-  Conversion?: ConversionService;
-  Tunnel?: TunnelHandler;
-  Program?: Command;
-  Behaviors?: BehaviorsService;
-  ComputerUse?: ComputerUseService;
-  Extensions?: ExtensionsService;
-  [key: string]: any;
-  Tracing?: typeof TracingServiceType;
-}
-
-export interface KnowhowModule {
-  /**
-   * Phase 1 (optional): called first, potentially with ONLY `Program` in
-   * context (e.g. during early CLI command registration). Use this to:
-   *   - register CLI subcommands on `context.Program`
-   *   - inject services into the shared context (e.g.
-   *     `context.Tools?.addContext("ComputerUse", svc)`) so that OTHER modules
-   *     (or a sibling adapter module) can consume them during their own init.
-   *
-   * `register` must be side-effect-light and MUST NOT assume the full service
-   * graph is present — only `Program` is guaranteed during the early phase.
-   * It may be called more than once (early CLI phase + full-services phase);
-   * implementations should be idempotent.
-   */
-  register?: (params: InitParams) => Promise<void>;
-  /**
-   * Phase 2: called with the full service graph available. Use this to
-   * actually connect/start things (open drivers, spin up watchers, read
-   * services registered by other modules' `register` phase, etc.).
-   */
-  init: (params: InitParams) => Promise<void>;
-  /**
-   * Phase 3 (optional): called when the CLI is shutting down. Use this to
-   * cleanly release resources — close connections, flush buffers, stop
-   * watchers, etc. Mirror of `init`.
-   */
-  destroy?: (params: InitParams) => Promise<void>;
-  commands: ModuleChatCommand[];
-  /** Optional capabilities consumed by core or third-party services. */
-  extensions?: ModuleExtension[];
-  tools: ModuleTool[];
-  agents: ModuleAgent[];
-  plugins: ModulePlugin[];
-  clients: ModuleClient[];
-}

package/src/services/types.ts

@@ -1,60 +0,0 @@
-import { Tool } from "../clients/types";
-
-export type ToolOverrideFunction = (
-  originalArgs: any[],
-  originalTool: Tool
-) => Promise<any> | any;
-
-export interface ToolOverrideRegistration {
-  pattern: string | RegExp;
-  override: ToolOverrideFunction;
-  priority: number;
-}
-
-export type ToolWrapper = (
-  originalFunction: (...args: any[]) => any,
-  originalArgs: any[],
-  originalTool: Tool
-) => Promise<any> | any;
-
-export interface ToolWrapperRegistration {
-  pattern: string | RegExp;
-  wrapper: ToolWrapper;
-  priority: number;
-}
-
-export interface PatternMatcher {
-  matches(toolName: string): boolean;
-  pattern: string | RegExp;
-}
-
-export class StringPatternMatcher implements PatternMatcher {
-  constructor(public pattern: string) {}
-
-  matches(toolName: string): boolean {
-    // Convert glob pattern to regex
-    const regexPattern = this.pattern
-      .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape special regex chars except * and ?
-      .replace(/\*/g, ".*") // Convert * to .*
-      .replace(/\?/g, "."); // Convert ? to .
-
-    const regex = new RegExp(`^${regexPattern}$`);
-    return regex.test(toolName);
-  }
-}
-
-export class RegexPatternMatcher implements PatternMatcher {
-  constructor(public pattern: RegExp) {}
-
-  matches(toolName: string): boolean {
-    return this.pattern.test(toolName);
-  }
-}
-
-export function createPatternMatcher(pattern: string | RegExp): PatternMatcher {
-  if (typeof pattern === "string") {
-    return new StringPatternMatcher(pattern);
-  } else {
-    return new RegexPatternMatcher(pattern);
-  }
-}

package/src/services/watchers/FsSyncer.ts

@@ -1,199 +0,0 @@
-import fs from "fs";
-import fsPromises from "fs/promises";
-import path from "path";
-
-import { SyncedAgentWatcher } from "../SyncedAgentWatcher";
-import { messagesToRenderEvents } from "../../chat/renderer/messagesToRenderEvents";
-import { EventService } from "../EventService";
-
-/**
- * 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 lastThreadIndex: number = -1;
-  private lastThreadLength: number = 0;
-  private lastMessageJson: string | null = null;
-  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.lastThreadIndex = threads.length - 1;
-      this.lastThreadLength = lastThread.length;
-      this.lastMessageJson = this.messageJson(lastThread[lastThread.length - 1]);
-    }
-
-    // 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] || [];
-
-    const threadIndex = threads.length - 1;
-    let newMessages: any[];
-    if (
-      threadIndex === this.lastThreadIndex &&
-      lastThread.length >= this.lastThreadLength
-    ) {
-      newMessages = lastThread.slice(this.lastThreadLength);
-    } else {
-      const retainedIndex = this.findLastMessage(
-        lastThread,
-        this.lastMessageJson
-      );
-      newMessages = lastThread.slice(retainedIndex + 1);
-    }
-
-    this.lastThreadIndex = threadIndex;
-    this.lastThreadLength = lastThread.length;
-    this.lastMessageJson = this.messageJson(lastThread[lastThread.length - 1]);
-
-    // Only render NEW messages since last check
-    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);
-    }
-
-    // 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}`);
-  }
-
-  async interrupt(message?: string): Promise<void> {
-    const inputPath = path.join(this.taskPath, "input.txt");
-    await fsPromises.writeFile(inputPath, `/poke ${message || ""}`.trim(), "utf8");
-    console.log(`🫵 Interrupt written to input for agent: ${this.taskId}`);
-  }
-
-  private messageJson(message: any): string | null {
-    if (message == null) return null;
-    try {
-      return JSON.stringify(message);
-    } catch {
-      return null;
-    }
-  }
-
-  private findLastMessage(messages: any[], messageJson: string | null): number {
-    if (messageJson == null) return -1;
-    for (let index = messages.length - 1; index >= 0; index--) {
-      if (this.messageJson(messages[index]) === messageJson) return index;
-    }
-    return -1;
-  }
-
-  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;
-    }
-  }
-}