@tyvm/knowhow 0.0.144 → 0.0.146

package/src/services/LazyToolsService.ts

@@ -80,6 +80,13 @@ export class LazyToolsService extends ToolsService {
     return this.tools; // Returns filtered subset
   }
 
+  /** Rebuild the lazy catalog while preserving enable/disable preferences. */
+  resetTools(): void {
+    this.allTools = [];
+    super.resetTools();
+    this.registerLazyTools();
+  }
+
   // Enable tools matching glob patterns
   enableTools(patterns: string[]) {
     for (const pattern of patterns) {

package/src/services/Mcp.ts

@@ -388,8 +388,15 @@ export class McpService {
   }
 
   async closeAll() {
-    await this.closeTransports();
-    await this.closeClients();
+    await Promise.allSettled([this.closeTransports()]);
+    await Promise.allSettled([this.closeClients()]);
+    // Connections are recreated from freshly-read configuration after reload.
+    this.clients = [];
+    this.transports = [];
+    this.connected = [];
+    this.config = [];
+    this.tools = [];
+    this.toolAliases = {};
   }
 
   getClientIndex(clientName: string) {

package/src/services/RuntimeReloadService.ts

@@ -0,0 +1,31 @@
+export interface RuntimeReloadResult {
+  tools: number;
+  mcps: number;
+  modules: number;
+}
+
+/** Coordinates in-place runtime refreshes and coalesces concurrent requests. */
+export class RuntimeReloadService {
+  private handler?: () => Promise<RuntimeReloadResult>;
+  private pending?: Promise<RuntimeReloadResult>;
+
+  configure(handler: () => Promise<RuntimeReloadResult>): void {
+    this.handler = handler;
+  }
+
+  isConfigured(): boolean {
+    return !!this.handler;
+  }
+
+  reload(): Promise<RuntimeReloadResult> {
+    if (!this.handler) {
+      return Promise.reject(new Error("Runtime reload is unavailable for this command"));
+    }
+    if (!this.pending) {
+      this.pending = this.handler().finally(() => {
+        this.pending = undefined;
+      });
+    }
+    return this.pending;
+  }
+}

package/src/services/SessionManager.ts

@@ -65,6 +65,10 @@ export class SessionManager {
         threads,
         currentThread: 0,
         lastUpdated: Date.now(),
+        model: taskInfo.model,
+        provider: taskInfo.provider,
+        reasoningEffort: taskInfo.reasoningEffort,
+        summarizeReasoning: taskInfo.summarizeReasoning,
       };
 
       fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));
@@ -101,6 +105,16 @@ export class SessionManager {
           session.knowhowMessageId = taskInfo.knowhowMessageId;
           session.knowhowTaskId = taskInfo.knowhowTaskId;
           session.chatSessionId = taskInfo.chatSessionId;
+
+          // Keep the persisted run configuration in sync (captures mid-run
+          // model/provider fallbacks) so a resume restores the exact setup.
+          if (taskInfo.model !== undefined) session.model = taskInfo.model;
+          if (taskInfo.provider !== undefined)
+            session.provider = taskInfo.provider;
+          if (taskInfo.reasoningEffort !== undefined)
+            session.reasoningEffort = taskInfo.reasoningEffort;
+          if (taskInfo.summarizeReasoning !== undefined)
+            session.summarizeReasoning = taskInfo.summarizeReasoning;
         }
 
         fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));

package/src/services/Tools.ts

@@ -34,6 +34,8 @@ export interface ToolCallContext {
   caller?: any;
   /** The task id of the calling agent, if known. */
   taskId?: string;
+  /** The task id of the parent agent that spawned the calling agent, if any. */
+  parentTaskId?: string;
   /** Arbitrary additional per-call context. */
   [key: string]: any;
 }
@@ -46,6 +48,7 @@ export interface ToolContext {
   Plugins?: PluginService;
   Mcp?: McpService;
   Behaviors?: BehaviorsService;
+  ComputerUse?: import("./modules/computerUse").ComputerUseService;
   metadata?: { [key: string]: any };
 }
 
@@ -76,6 +79,17 @@ export class ToolsService {
     }
   }
 
+  /**
+   * Remove every registered tool and handler while retaining service context,
+   * wrappers, and overrides. Runtime reload uses this before rebuilding the
+   * catalog from built-ins, MCP servers, and configured modules.
+   */
+  resetTools(): void {
+    this.tools = [];
+    this.functions = {};
+    this.originalFunctions = {};
+  }
+
   getContext(): ToolContext {
     return this.context;
   }

package/src/services/TracingService.ts

@@ -0,0 +1,116 @@
+/**
+ * TracingService — a zero-dependency, no-op-by-default tracing abstraction
+ * for the @tyvm/knowhow core package.
+ *
+ * The core package ships with NO OpenTelemetry dependencies. This service
+ * defines the interface that the decorators in `src/util/Trace.ts` call into,
+ * and holds a singleton "current tracer" that starts as a no-op.
+ *
+ * A module (e.g. @tyvm/knowhow-module-tracing) can call
+ * `TracingService.register(impl)` during its `init()` to swap in a real OTEL
+ * implementation. After that, every @Trace / @TraceAll / tracify call in the
+ * knowhow codebase will produce real spans — with zero changes to the core.
+ */
+
+export interface SpanHandle {
+  /** Set a string/number/boolean attribute on the span. */
+  setAttribute(key: string, value: string | number | boolean): void;
+  /** Mark the span as errored and record the exception. */
+  recordError(err: unknown): void;
+  /** End the span (records wall-clock end time). */
+  end(): void;
+}
+
+export interface TracerImpl {
+  /**
+   * Start a span. The implementation is responsible for making it a child of
+   * the currently-active span (via OpenTelemetry context propagation or
+   * equivalent).
+   *
+   * @param name        Span name, e.g. "ClassName.methodName"
+   * @param attributes  Initial attributes to attach
+   */
+  startSpan(
+    name: string,
+    attributes?: Record<string, string | number | boolean>
+  ): SpanHandle;
+
+  /**
+   * Run `fn` with the given span active so that child spans created inside it
+   * are automatically parented to this one.
+   *
+   * If context propagation is not supported, implementations can simply call
+   * `fn()` directly.
+   */
+  withSpan<T>(span: SpanHandle, fn: () => T): T;
+}
+
+// ─── No-op implementation used until a real tracer is registered ─────────────
+
+const noopSpan: SpanHandle = {
+  setAttribute() {},
+  recordError() {},
+  end() {},
+};
+
+const noopTracer: TracerImpl = {
+  startSpan() {
+    return noopSpan;
+  },
+  withSpan(_span, fn) {
+    return fn();
+  },
+};
+
+// ─── Singleton state ──────────────────────────────────────────────────────────
+
+let _impl: TracerImpl = noopTracer;
+
+/**
+ * TracingService — access point for the current tracer implementation.
+ *
+ * Usage in decorators / instrumentation code:
+ * ```ts
+ * import { TracingService } from '../services/TracingService';
+ * const span = TracingService.startSpan('MyClass.myMethod');
+ * ```
+ *
+ * Usage in a module to plug in a real OTEL tracer:
+ * ```ts
+ * import { TracingService } from '@tyvm/knowhow/...';
+ * TracingService.register(myOtelTracerImpl);
+ * ```
+ */
+export const TracingService = {
+  /**
+   * Register a real tracer implementation. Called by the tracing module during
+   * `init()`. The registration is global and immediate — all subsequent
+   * decorator/tracify calls will use this implementation.
+   */
+  register(impl: TracerImpl): void {
+    _impl = impl;
+  },
+
+  /** Reset to the no-op tracer (useful for tests). */
+  reset(): void {
+    _impl = noopTracer;
+  },
+
+  /** Whether a real (non-no-op) tracer has been registered. */
+  isEnabled(): boolean {
+    return _impl !== noopTracer;
+  },
+
+  /** Start a span using the current implementation. */
+  startSpan(
+    name: string,
+    attributes?: Record<string, string | number | boolean>
+  ): SpanHandle {
+    return _impl.startSpan(name, attributes);
+  },
+
+  /** Run a function with a span active (context propagation). */
+  withSpan<T>(span: SpanHandle, fn: () => T): T {
+    return _impl.withSpan(span, fn);
+  },
+};

package/src/services/index.ts

@@ -15,8 +15,10 @@ import { SessionManager } from "./SessionManager";
 import { TaskRegistry } from "./TaskRegistry";
 import { MediaProcessorService } from "./MediaProcessorService";
 import { BehaviorsService } from "./BehaviorsService";
+import { RuntimeReloadService } from "./RuntimeReloadService";
 
 import { ConversionService } from "./conversion/ConversionService";
+import { TracingService } from "./TracingService";
 
 export * from "./AgentService";
 export * from "./EventService";
@@ -38,7 +40,11 @@ export * from "./SyncedAgentWatcher";
 export * from "./SyncerService";
 export * from "./watchers";
 export { Clients } from "../clients";
+export * from "../util/Trace";
+export { TracingService } from "./TracingService";
+export type { TracerImpl, SpanHandle } from "./TracingService";
 export * from "./conversion";
+export * from "./RuntimeReloadService";
 export { BehaviorsService } from "./BehaviorsService";
 
 let Singletons = {} as {
@@ -56,6 +62,7 @@ let Singletons = {} as {
   MediaProcessor: MediaProcessorService;
   Conversion: ConversionService;
   Behaviors: BehaviorsService;
+  RuntimeReload: RuntimeReloadService;
 };
 
 export const services = (): typeof Singletons => {
@@ -88,6 +95,7 @@ export const services = (): typeof Singletons => {
       Tools,
       knowhowApiClient: new KnowhowSimpleClient(),
       Behaviors,
+      RuntimeReload: new RuntimeReloadService(),
     };
 
     Singletons.Tools.setContext({

package/src/services/modules/computerUse.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared, driver-agnostic interface for the computer-use service.
+ *
+ * The concrete implementation lives in `@tyvm/knowhow-module-computer-use`, but
+ * we declare the shape here so that `ToolContext` / `ModuleContext` can carry a
+ * `ComputerUse` service without the core knowhow package taking a runtime
+ * dependency on the module.
+ *
+ * An adapter module (e.g. `@tyvm/knowhow-module-computer-use-nutjs`) can
+ * register a `ComputerDriver` against the service in its `register` phase; the
+ * base module then `init()`s and picks the best available driver.
+ */
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface Region extends Point, Size {}
+
+export type MouseButton = "left" | "right" | "middle";
+
+export interface OverlayPrimitive {
+  kind: "rect" | "circle" | "line" | "point";
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  x2?: number;
+  y2?: number;
+  color?: string;
+  lineWidth?: number;
+}
+
+export interface Display {
+  id: number;
+  bounds: Region;
+  scaleFactor: number;
+  primary: boolean;
+}
+
+export interface ScreenshotOptions {
+  region?: Region;
+  displayId?: number;
+  format?: "png" | "jpeg";
+  scale?: number;
+  /** Native capture downscale. Unlike output encoding scale, drivers may apply
+   * this before raw pixels cross the process boundary. */
+  captureScale?: number;
+}
+
+export interface DriverCapabilities {
+  input: boolean;
+  capture: boolean;
+  windows: boolean;
+  reason?: string;
+}
+
+export interface AccessibilityElement {
+  id: string;
+  role: string;
+  subrole?: string;
+  title?: string;
+  description?: string;
+  value?: string;
+  enabled?: boolean;
+  focused?: boolean;
+  bounds?: Region;
+  actions: string[];
+  childCount: number;
+}
+
+export interface AccessibilityOptions {
+  maxDepth?: number;
+  maxElements?: number;
+  interactiveOnly?: boolean;
+}
+
+/**
+ * The engine seam. Concrete drivers (Rust core, CLI adapter, nut.js demo)
+ * implement this. Registered with the service via `registerDriver`.
+ */
+export interface ComputerDriver {
+  readonly name: string;
+  /**
+   * Lower numbers win when multiple drivers are registered. The default Rust
+   * core registers at 100; a fallback CLI adapter at 500; an experimental demo
+   * adapter can register at e.g. 10 to force selection.
+   */
+  readonly priority?: number;
+
+  capabilities(): Promise<DriverCapabilities>;
+
+  // screen
+  getDisplays(): Promise<Display[]>;
+  screenSize(): Promise<Size>;
+  screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
+  pixelColor(p: Point): Promise<string>;
+
+  // mouse
+  mousePosition(): Promise<Point>;
+  moveMouse(p: Point, opts?: { duration?: number }): Promise<void>;
+  click(button?: MouseButton, opts?: { double?: boolean }): Promise<void>;
+  mouseDown(button?: MouseButton): Promise<void>;
+  mouseUp(button?: MouseButton): Promise<void>;
+  drag(
+    from: Point,
+    to: Point,
+    opts?: { button?: MouseButton; duration?: number }
+  ): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+
+  // keyboard
+  typeText(text: string, opts?: { delay?: number }): Promise<void>;
+  pressKey(key: string): Promise<void>;
+  hotkey(...keys: string[]): Promise<void>;
+  keyDown(key: string): Promise<void>;
+  keyUp(key: string): Promise<void>;
+
+  // windows (optional / capability-gated)
+  getActiveWindow?(): Promise<{ title: string; app?: string; bounds?: Region } | null>;
+  listWindows?(): Promise<Array<{ title: string; app?: string; bounds?: Region }>>;
+  focusWindow?(match: string): Promise<boolean>;
+
+  accessibilityTrusted?(): Promise<boolean>;
+  accessibilityElements?(options?: AccessibilityOptions): Promise<AccessibilityElement[]>;
+  setAccessibilityValue?(id: string, value: string): Promise<void>;
+  performAccessibilityAction?(id: string, action: string): Promise<void>;
+
+  // click-through visual debugging (optional / platform capability-gated)
+  showOverlay?(primitives: OverlayPrimitive[]): Promise<void>;
+  clearOverlay?(): Promise<void>;
+
+  dispose?(): Promise<void>;
+}
+
+/**
+ * The registered service (`ComputerUse`) surfaced to tools/CLI/MCP. It owns
+ * driver selection and provides the normalized, platform-agnostic verbs.
+ *
+ * We keep this as an interface (not a class) in the core package so the module
+ * owns the concrete implementation; anything reading `context.ComputerUse`
+ * codes against this contract.
+ */
+export interface ComputerUseService {
+  /** Register a driver (called by the base module and any adapter modules). */
+  registerDriver(driver: ComputerDriver): void;
+  /** List the names of all registered drivers. */
+  listDrivers(): string[];
+  /** Resolve/select the active driver (highest priority + capable). */
+  getDriver(): Promise<ComputerDriver>;
+
+  capabilities(): Promise<DriverCapabilities>;
+  getDisplays(): Promise<Display[]>;
+  screenSize(): Promise<Size>;
+  /** Returns encoded image bytes (PNG/JPEG) honoring service defaults. */
+  screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
+  /** Convenience: base64 data (no data: prefix) for multimodal messages. */
+  screenshotBase64(opts?: ScreenshotOptions): Promise<string>;
+  pixelColor(p: Point): Promise<string>;
+
+  mousePosition(): Promise<Point>;
+  moveMouse(p: Point, opts?: { duration?: number }): Promise<void>;
+  click(button?: MouseButton, opts?: { double?: boolean }): Promise<void>;
+  drag(
+    from: Point,
+    to: Point,
+    opts?: { button?: MouseButton; duration?: number }
+  ): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  /** Smooth stepped scrolling (repeat a small delta with a pause between). */
+  scrollBy?(
+    dx: number,
+    dy: number,
+    opts?: { repeat?: number; intervalMs?: number }
+  ): Promise<void>;
+
+  typeText(text: string, opts?: { delay?: number }): Promise<void>;
+  pressKey(key: string): Promise<void>;
+  hotkey(...keys: string[]): Promise<void>;
+
+  /** Screenshot with an optional labeled grid and/or crosshair overlay. */
+  screenshotAnnotated?(
+    opts?: ScreenshotOptions & {
+      grid?: boolean;
+      gridStep?: number;
+      crosshair?: Point;
+    }
+  ): Promise<Buffer>;
+
+  getActiveWindow(): Promise<{
+    title: string;
+    app?: string;
+    bounds?: Region;
+  } | null>;
+  listWindows(): Promise<
+    Array<{ title: string; app?: string; bounds?: Region }>
+  >;
+  focusWindow(match: string): Promise<boolean>;
+
+  accessibilityTrusted(): Promise<boolean>;
+  accessibilityElements(options?: AccessibilityOptions): Promise<AccessibilityElement[]>;
+  selectAccessibilityOption(id: string, option: string): Promise<void>;
+  setAccessibilityValue(id: string, value: string): Promise<void>;
+  performAccessibilityAction(id: string, action: string): Promise<void>;
+
+  showOverlay(primitives: OverlayPrimitive[]): Promise<void>;
+  clearOverlay(): Promise<void>;
+
+  dispose(): Promise<void>;
+}

package/src/services/modules/index.ts

@@ -39,6 +39,13 @@ function globalResolvePaths(): string[] {
 }
 
 export class ModulesService {
+  private _loadedModules: {
+    modulePath: string;
+    resolvedPath: string;
+    module: KnowhowModule;
+    params: any;
+  }[] = [];
+
   async getDefaultContext() {
     return { ...services() };
   }
@@ -75,6 +82,22 @@ export class ModulesService {
     // 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
@@ -113,6 +136,7 @@ export class ModulesService {
       // global install).
       let importedModule: KnowhowModule;
       let loaded = false;
+      let selectedResolvedPath = modulePath;
       const errors: { candidate: string; error: Error }[] = [];
       for (const resolvedPath of candidates) {
         try {
@@ -122,15 +146,17 @@ export class ModulesService {
             "ModulesService",
             `🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`
           );
-          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})`
-          );
+          // 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) {
@@ -152,6 +178,35 @@ export class ModulesService {
         );
         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 });
+
       // 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) {
@@ -188,6 +243,32 @@ export class ModulesService {
     }
   }
 
+  /**
+   * 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) {
+      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();
 

package/src/services/modules/types.ts

@@ -14,7 +14,9 @@ import { TunnelHandler } from "@tyvm/knowhow-tunnel";
 import { EventService } from "../EventService";
 import { ConversionService } from "../conversion/ConversionService";
 import { BehaviorsService } from "../BehaviorsService";
+import { ComputerUseService } from "./computerUse";
 
+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
@@ -62,11 +64,39 @@ export interface ModuleContext {
   Conversion?: ConversionService;
   Tunnel?: TunnelHandler;
   Program?: Command;
-  Behaviors?: BehaviorsService
+  Behaviors?: BehaviorsService;
+  ComputerUse?: ComputerUseService;
+  [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[];
   tools: ModuleTool[];
   agents: ModuleAgent[];