@tyvm/knowhow 0.0.143 → 0.0.145

package/src/processors/Base64ImageDetector.ts

@@ -257,11 +257,26 @@ export class Base64ImageProcessor {
       try {
         // Try to parse as JSON
         const parsed = JSON.parse(message.content);
-        
-        // Check if it's an image_url object
-        if (parsed.type === "image_url" && parsed.image_url?.url) {
-          // Convert the tool message content from JSON string to an array with the image
-          message.content = [parsed];
+
+        // Normalize the parsed value into an array of candidate parts so we can
+        // handle BOTH shapes a tool might return:
+        //   1. a single image_url object:  {type:"image_url", image_url:{url}}
+        //   2. an array of parts:          [{type:"image_url", image_url:{url}}, {type:"text", ...}]
+        // (Computer-use screenshot tools and loadWebpage return the array form,
+        //  which the single-object check above previously missed — leaving the
+        //  model to see a raw base64 JSON string instead of an actual image.)
+        const candidates = Array.isArray(parsed) ? parsed : [parsed];
+        const isImagePart = (p: any) =>
+          p && p.type === "image_url" && p.image_url?.url;
+        const isTextPart = (p: any) =>
+          p && p.type === "text" && typeof p.text === "string";
+
+        // Only rewrite the content if it actually contains at least one image
+        // part; otherwise leave the original tool text untouched.
+        if (candidates.some(isImagePart)) {
+          message.content = candidates.filter(
+            (p) => isImagePart(p) || isTextPart(p)
+          );
         }
       } catch (e) {
         // Not JSON, check if it's a plain base64 string (only if still a string)
@@ -414,10 +429,34 @@ export class Base64ImageProcessor {
 
       // Read the file as base64
       const imageBuffer = fs.readFileSync(filePath);
+
+      // Detect actual MIME type from magic bytes (overrides extension-based detection)
+      // This handles cases where a file is saved with the wrong extension (e.g. JPEG saved as .png)
+      let detectedMimeType = mimeType;
+      if (imageBuffer.length >= 4) {
+        // JPEG: starts with FF D8 FF
+        if (imageBuffer[0] === 0xff && imageBuffer[1] === 0xd8 && imageBuffer[2] === 0xff) {
+          detectedMimeType = "image/jpeg";
+        }
+        // PNG: starts with 89 50 4E 47 0D 0A 1A 0A
+        else if (imageBuffer[0] === 0x89 && imageBuffer[1] === 0x50 && imageBuffer[2] === 0x4e && imageBuffer[3] === 0x47) {
+          detectedMimeType = "image/png";
+        }
+        // GIF: starts with 47 49 46 38 (GIF8)
+        else if (imageBuffer[0] === 0x47 && imageBuffer[1] === 0x49 && imageBuffer[2] === 0x46 && imageBuffer[3] === 0x38) {
+          detectedMimeType = "image/gif";
+        }
+        // WebP: starts with 52 49 46 46 (RIFF) ... 57 45 42 50 (WEBP) at offset 8
+        else if (imageBuffer.length >= 12 && imageBuffer[0] === 0x52 && imageBuffer[1] === 0x49 && imageBuffer[2] === 0x46 && imageBuffer[3] === 0x46 &&
+                 imageBuffer[8] === 0x57 && imageBuffer[9] === 0x45 && imageBuffer[10] === 0x42 && imageBuffer[11] === 0x50) {
+          detectedMimeType = "image/webp";
+        }
+      }
+
       const base64Data = imageBuffer.toString("base64");
 
-      // Create data URL
-      const dataUrl = `data:${mimeType};base64,${base64Data}`;
+      // Create data URL using the actual detected MIME type
+      const dataUrl = `data:${detectedMimeType};base64,${base64Data}`;
 
       // Return in a format that indicates this is an image
       // The Base64ImageDetector will convert this to proper image content

package/src/processors/GemmaToolProcessor.ts

@@ -0,0 +1,163 @@
+import { Message, ToolCall } from "../clients/types";
+import { MessageProcessorFunction } from "../services/MessageProcessor";
+
+/**
+ * Gemma 4 Tool Call Processor
+ *
+ * Gemma 4 uses a non-standard tool-call format with its own string-quoting token:
+ *
+ *   <|tool_call>call:toolName{key:<|"|>string value<|"|>,numKey:42,boolKey:true}<tool_call|>
+ *
+ * Strings are delimited by <|"|> instead of standard JSON quotes.
+ * Numbers and booleans are written bare (no quotes).
+ * Multiple tool calls may appear in a single assistant message.
+ *
+ * Reference: https://ai.google.dev/gemma/docs/capabilities/text/function-calling-gemma4
+ */
+export class GemmaToolProcessor {
+  private static instance: GemmaToolProcessor;
+
+  static getInstance(): GemmaToolProcessor {
+    if (!GemmaToolProcessor.instance) {
+      GemmaToolProcessor.instance = new GemmaToolProcessor();
+    }
+    return GemmaToolProcessor.instance;
+  }
+
+  // ── Detection ─────────────────────────────────────────────────────────────
+
+  /** Returns true when the content looks like it contains Gemma tool-call tokens. */
+  private isGemmaFormat(content: string): boolean {
+    return content.includes("<|tool_call>") && content.includes("<tool_call|>");
+  }
+
+  // ── Parsing ───────────────────────────────────────────────────────────────
+
+  /**
+   * Cast a raw argument value string to a JS primitive.
+   * Mirrors the Python `cast()` helper from the official docs.
+   */
+  private castValue(raw: string): string | number | boolean {
+    const trimmed = raw.trim();
+
+    // Boolean
+    const lower = trimmed.toLowerCase();
+    if (lower === "true") return true;
+    if (lower === "false") return false;
+
+    // Integer
+    if (/^-?\d+$/.test(trimmed)) return parseInt(trimmed, 10);
+
+    // Float
+    if (/^-?\d+\.\d*$/.test(trimmed)) return parseFloat(trimmed);
+
+    // Strip surrounding single/double quotes that the model might emit
+    return trimmed.replace(/^['"]|['"]$/g, "");
+  }
+
+  /**
+   * Parse the argument body of a single Gemma tool call.
+   *
+   * The body looks like:
+   *   key1:<|"|>string value<|"|>,key2:42,key3:true
+   *
+   * The regex (from the official docs) handles both quoted strings and bare values:
+   *   (\w+):(?:<|"|>(.*?)<|"|>|([^,}]*))
+   */
+  private parseArgs(argsBody: string): Record<string, string | number | boolean> {
+    const result: Record<string, string | number | boolean> = {};
+
+    // Regex from the official Google Gemma 4 function-calling docs
+    const argPattern = /(\w+):(?:<\|"\|>(.*?)<\|"\|>|([^,}]*))/gs;
+    let m: RegExpExecArray | null;
+
+    while ((m = argPattern.exec(argsBody)) !== null) {
+      const key = m[1];
+      // v1: string inside <|"|>…<|"|>   v2: bare value
+      const rawValue = m[2] !== undefined ? m[2] : m[3] ?? "";
+      result[key] = m[2] !== undefined ? rawValue : this.castValue(rawValue);
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract all Gemma tool calls from an assistant message string.
+   * Returns an array of { toolName, arguments } objects.
+   */
+  private extractGemmaToolCalls(
+    content: string
+  ): { toolName: string; arguments: string }[] {
+    const results: { toolName: string; arguments: string }[] = [];
+
+    // Outer pattern: <|tool_call>call:name{args}<tool_call|>
+    // Using DOTALL-equivalent workaround: [\s\S] for multi-line args
+    const outerPattern = /<\|tool_call>call:(\w+)\{([\s\S]*?)\}<tool_call\|>/g;
+    let match: RegExpExecArray | null;
+
+    while ((match = outerPattern.exec(content)) !== null) {
+      const toolName = match[1];
+      const argsBody = match[2];
+
+      const parsed = this.parseArgs(argsBody);
+      results.push({
+        toolName,
+        arguments: JSON.stringify(parsed),
+      });
+    }
+
+    return results;
+  }
+
+  // ── Conversion ────────────────────────────────────────────────────────────
+
+  private generateToolCallId(): string {
+    return `gemma_call_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private toToolCalls(
+    extracted: { toolName: string; arguments: string }[]
+  ): ToolCall[] {
+    return extracted.map(({ toolName, arguments: args }) => ({
+      id: this.generateToolCallId(),
+      type: "function" as const,
+      function: {
+        name: toolName,
+        arguments: args,
+      },
+    }));
+  }
+
+  // ── Message processing ────────────────────────────────────────────────────
+
+  private processMessage(message: Message): void {
+    if (message.role !== "assistant") return;
+    if (typeof message.content !== "string") return;
+    if (message?.tool_calls?.length) return;
+
+    if (!this.isGemmaFormat(message.content)) return;
+
+    const extracted = this.extractGemmaToolCalls(message.content);
+    if (extracted.length === 0) return;
+
+    const toolCalls = this.toToolCalls(extracted);
+
+    if (message.tool_calls) {
+      message.tool_calls.push(...toolCalls);
+    } else {
+      message.tool_calls = toolCalls;
+    }
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  createProcessor(): MessageProcessorFunction {
+    return (_originalMessages: Message[], modifiedMessages: Message[]): void => {
+      for (const message of modifiedMessages) {
+        this.processMessage(message);
+      }
+    };
+  }
+}
+
+export const globalGemmaToolProcessor = new GemmaToolProcessor();

package/src/processors/index.ts

@@ -10,4 +10,5 @@ export {
 export { ToolResponseCache } from "./ToolResponseCache";
 export { XmlToolCallProcessor } from "./XmlToolCallProcessor";
 export { HarmonyToolProcessor } from "./HarmonyToolProcessor";
+export { GemmaToolProcessor } from "./GemmaToolProcessor";
 export { MinimalToolsMessageProcessor } from "./MinimalToolsMessageProcessor";

package/src/services/AgentSyncFs.ts

@@ -133,6 +133,11 @@ export class AgentSyncFs {
    * that call) to usage.json. This is intended for debugging cache-hit
    * issues, where comparing the message chains and usage values between
    * consecutive calls can reveal when a cache prefix was invalidated.
+   *
+   * To prevent exponential file growth, if the new entry's message thread
+   * fully contains the previous entry's thread as a prefix, the previous
+   * thread is replaced with { PREV_CACHE_HIT: true } so only the new
+   * messages (the delta) are stored alongside the new usage data.
    */
   private async appendUsageEntry(entry: any): Promise<void> {
     if (!this.taskPath) return;
@@ -148,6 +153,27 @@ export class AgentSyncFs {
         // File doesn't exist or is invalid, start fresh
       }
 
+      // If the new entry's messages are a superset of the last entry's
+      // messages (i.e. the last thread is a prefix of the new thread),
+      // collapse the last entry's messages to { PREV_CACHE_HIT: true }
+      // and store only the new delta — preventing exponential growth.
+      if (entries.length > 0) {
+        const lastEntry = entries[entries.length - 1];
+        const prevMessages: any[] = lastEntry?.messages;
+        const newMessages: any[] = entry?.messages;
+        if (
+          Array.isArray(prevMessages) &&
+          Array.isArray(newMessages) &&
+          prevMessages.length > 0 &&
+          newMessages.length >= prevMessages.length &&
+          JSON.stringify(newMessages.slice(0, prevMessages.length)) ===
+            JSON.stringify(prevMessages)
+        ) {
+          // Replace the previous full thread with a compact sentinel
+          lastEntry.messages = [{ PREV_CACHE_HIT: true }];
+        }
+      }
+
       entries.push(entry);
       await fs.writeFile(usagePath, JSON.stringify(entries, null, 2), "utf8");
     } catch (error) {
@@ -180,6 +206,17 @@ export class AgentSyncFs {
       metadata.totalCostUsd = agent.getTotalCostUsd();
       metadata.tokenUsage = agent.getTokenUsage();
       metadata.agentName = agent.name;
+      // Record the model/provider actually in use at this sync so task
+      // history reflects the real model (including mid-run fallbacks), not
+      // just the named agent.
+      metadata.model = agent.getModel();
+      metadata.provider = agent.getProvider();
+      // Persist reasoning settings so a resume can restore the exact
+      // reasoning effort / summarize behavior the run was using. (The
+      // encrypted reasoning items + summaries themselves ride along on the
+      // thread messages via `_reasoning_details` / `reasoning_summary`.)
+      metadata.reasoningEffort = agent.getReasoningEffort?.();
+      metadata.summarizeReasoning = agent.getSummarizeReasoning?.();
       metadata.inProgress = inProgress;
       metadata.lastUpdate = new Date().toISOString();
 

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 };
 }
 

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

@@ -75,6 +75,21 @@ 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;
+      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
@@ -122,15 +137,16 @@ 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,
+            });
+          }
           loaded = true;
           break;
         } catch (err: any) {
@@ -152,6 +168,28 @@ export class ModulesService {
         );
         continue;
       }
+      loadedModules.push({ modulePath, 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, module: importedModule } of loadedModules) {
+      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;
+      }
       // 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) {

package/src/services/modules/types.ts

@@ -14,6 +14,7 @@ import { TunnelHandler } from "@tyvm/knowhow-tunnel";
 import { EventService } from "../EventService";
 import { ConversionService } from "../conversion/ConversionService";
 import { BehaviorsService } from "../BehaviorsService";
+import { ComputerUseService } from "./computerUse";
 
 /*
  *
@@ -62,10 +63,31 @@ export interface ModuleContext {
   Conversion?: ConversionService;
   Tunnel?: TunnelHandler;
   Program?: Command;
-  Behaviors?: BehaviorsService
+  Behaviors?: BehaviorsService;
+  ComputerUse?: ComputerUseService;
+  [key: string]: any;
 }
 
 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>;
   commands: ModuleChatCommand[];
   tools: ModuleTool[];