@tyvm/knowhow 0.0.144 → 0.0.146

package/src/commands/services.ts

@@ -1,6 +1,6 @@
 import { includedTools } from "../agents/tools/list";
 import * as allTools from "../agents/tools";
-import { LazyToolsService, services, MinimalToolsService } from "../services";
+import { LazyToolsService, services, MinimalToolsService, TracingService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
 import { getConfig } from "../config";
@@ -19,8 +19,10 @@ export async function setupServices() {
     Events,
     MediaProcessor,
     Behaviors,
+    RuntimeReload,
   } = services();
 
+  await Plugins.refreshConfiguredState();
   // cli uses LazyTools to keep context slim
   const Tools = new LazyToolsService();
   await Behaviors.initFromConfig();
@@ -80,7 +82,7 @@ export async function setupServices() {
 
   console.log("📦 Loading modules from config...");
   const modulesService = new ModulesService();
-  await modulesService.loadModulesFromConfig({
+  const moduleContext = {
     Agents,
     Embeddings,
     Plugins,
@@ -89,7 +91,51 @@ export async function setupServices() {
     MediaProcessor,
     Behaviors,
     Events,
+    Tracing: TracingService,
+  };
+
+  // Call destroy() on all modules when the process is shutting down so they
+  // can flush buffers (e.g. OTEL spans), close connections, etc.
+  const destroyAll = async () => {
+    await modulesService.destroyModules();
+  };
+  process.on("beforeExit", destroyAll);
+  process.on("SIGINT", async () => {
+    await destroyAll();
+    process.exit(0);
+  });
+  await modulesService.loadModulesFromConfig(moduleContext);
+
+  RuntimeReload.configure(async () => {
+    await modulesService.destroyModules();
+    await Plugins.refreshConfiguredState();
+    await Mcp.closeAll();
+
+    Tools.resetTools();
+    Tools.defineTools(includedTools, allTools);
+    try {
+      const agentCallDef = AllTools.getTool?.("agentCall");
+      const agentCallFn = AllTools.getFunction?.("agentCall");
+      if (agentCallDef) Tools.addTool(agentCallDef);
+      if (agentCallFn) Tools.setFunction("agentCall", agentCallFn);
+    } catch (_) {}
+
+    await Behaviors.initFromConfig();
+    await Mcp.connectToConfigured(Tools);
+    await Clients.registerConfiguredModels();
+    await modulesService.loadModulesFromConfig(moduleContext);
+
+    const config = await getConfig();
+    return {
+      tools: Tools.getTools().length,
+      mcps: (config.mcps || []).length,
+      modules: (config.modules || []).length,
+    };
+  });
+  process.on("SIGTERM", async () => {
+    await destroyAll();
+    process.exit(0);
   });
 
-  return { Tools, Clients };
+  return { Tools, Clients, modulesService };
 }

package/src/index.ts

@@ -51,6 +51,14 @@ export {
 } from "./generate";
 
 export * as clients from "./clients";
+export type {
+  Tool,
+  ToolProp,
+  ToolCall,
+  Message,
+  CompletionOptions,
+  CompletionResponse,
+} from "./clients/types";
 export * as agents from "./agents";
 export * as services from "./services";
 export * as embeddings from "./embeddings";
@@ -61,6 +69,7 @@ export * as ai from "./ai";
 // Export module system types for external modules
 export * from "./services/modules/types";
 export { ModulesService } from "./services/modules";
+export * from "./services/modules/computerUse";
 // Export conversion types for external modules (e.g. knowhow-module-pdf)
 export * from "./services/conversion/types";
 export { ConversionService } from "./services/conversion/ConversionService";

package/src/plugins/plugins.ts

@@ -52,6 +52,22 @@ export class PluginService {
     return true;
   }
 
+  /** Apply the enabled/disabled state from the current Knowhow config. */
+  async refreshConfiguredState(): Promise<void> {
+    const config = await getConfig();
+    const disabled = new Set(getDisabledPlugins(config.plugins));
+
+    for (const [key, plugin] of this.pluginMap) {
+      if (disabled.has(key)) {
+        plugin.disable();
+      } else {
+        // Configuration is authoritative when services start or reload. This
+        // also re-enables a plugin after it is removed from `disabled`.
+        plugin.enable();
+      }
+    }
+  }
+
   /* -------- existing public API (updated for compatibility) ---------------------- */
 
   listPlugins() {

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/TokenCompressor.ts

@@ -7,6 +7,7 @@ import {
   CompressionMetadata,
   JsonCompressorStorage,
 } from "./JsonCompressor";
+import { paginateToolResponse } from "./tools/boundedToolResponse";
 
 export interface KeyInfo {
   key: string;
@@ -419,15 +420,25 @@ export class TokenCompressor implements JsonCompressorStorage {
     if (toolsService) {
       toolsService.addTools([expandTokensDefinition]);
       toolsService.addFunctions({
-        [this.toolName]: (key: string, fromLine?: number, toLine?: number) => {
+        [this.toolName]: (
+          key: string,
+          fromLine?: number,
+          toLine?: number,
+          characterOffset?: number,
+          maxCharacters?: number
+        ) => {
           // Auto-stitch: follow any NEXT_CHUNK_KEY chain and return the full,
           // reassembled content so the agent never has to chase nested keys.
           const data = this.retrieveFullString(key);
 
           if (data === null) {
-            return `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
-              ", "
-            )}`;
+            return paginateToolResponse(
+              `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
+                ", "
+              )}`,
+              { characterOffset, maxCharacters },
+              "available-key list"
+            );
           }
 
           // Optional ranged read: return only the requested 1-based, inclusive
@@ -435,7 +446,11 @@ export class TokenCompressor implements JsonCompressorStorage {
           const hasRange =
             typeof fromLine === "number" || typeof toLine === "number";
           if (!hasRange) {
-            return data;
+            return paginateToolResponse(
+              data,
+              { characterOffset, maxCharacters },
+              `expanded value for ${key}`
+            );
           }
 
           const lines = data.split("\n");
@@ -447,14 +462,22 @@ export class TokenCompressor implements JsonCompressorStorage {
           );
 
           if (start > end) {
-            return `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`;
+            return paginateToolResponse(
+              `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`,
+              { characterOffset, maxCharacters },
+              "line-range error"
+            );
           }
 
           const numbered: string[] = [];
           for (let i = start; i <= end; i++) {
             numbered.push(`${i}: ${lines[i - 1]}`);
           }
-          return numbered.join("\n");
+          return paginateToolResponse(
+            numbered.join("\n"),
+            { characterOffset, maxCharacters },
+            `expanded lines ${start}-${end} for ${key}`
+          );
         },
       });
     }
@@ -559,7 +582,7 @@ export const expandTokensDefinition: Tool = {
   function: {
     name: "expandTokens",
     description:
-      "Retrieve compressed data that was stored during message processing. The full content is automatically reassembled (any chunk chain is followed for you, so you never need to chase NEXT_CHUNK_KEY references). Optionally pass fromLine/toLine (1-based, inclusive) to return just a range of lines, prefixed with real line numbers. NOTE: Can also use jqToolResponse, grepToolResponse, tailToolResponse to access/filter/search compressed content without needing to expand all tokens.",
+      "Retrieve a bounded page of compressed data. Chunk chains are automatically reassembled, but output is limited to 20,000 characters by default. Use characterOffset to continue, or fromLine/toLine for line-based selection. Prefer jqToolResponse, grepToolResponse, or tailToolResponse when possible.",
     parameters: {
       type: "object",
       positional: true,
@@ -578,6 +601,15 @@ export const expandTokensDefinition: Tool = {
           description:
             "Optional 1-based end line (inclusive). Defaults to the end of the content when omitted.",
         },
+        characterOffset: {
+          type: "number",
+          description:
+            "Optional zero-based character offset within the expanded value or selected line range.",
+        },
+        maxCharacters: {
+          type: "number",
+          description: "Response size (default 20000, hard maximum 50000).",
+        },
       },
       required: ["key"],
     },

package/src/processors/ToolResponseCache.ts

@@ -5,6 +5,7 @@ import { JsonCompressor } from "./JsonCompressor";
 import {
   jqToolResponseDefinition,
   executeJqQuery,
+  JqOptions,
   grepToolResponseDefinition,
   executeGrep,
   GrepOptions,
@@ -13,6 +14,7 @@ import {
   TailOptions,
   listStoredToolResponsesDefinition,
   executeListStoredToolResponses,
+  ListStoredToolResponsesOptions,
 } from "./tools";
 
 interface ToolResponseStorage {
@@ -196,11 +198,12 @@ export class ToolResponseCache {
    */
   async queryToolResponse(
     toolCallId: string,
-    jqQuery: string
+    jqQuery: string,
+    options?: JqOptions
   ): Promise<string> {
     const data = this.storage[toolCallId];
     const availableIds = Object.keys(this.storage);
-    return executeJqQuery(data, toolCallId, jqQuery, availableIds, this.toolNameMap);
+    return executeJqQuery(data, toolCallId, jqQuery, availableIds, this.toolNameMap, options);
   }
 
   /**
@@ -231,11 +234,14 @@ export class ToolResponseCache {
   /**
    * List all stored tool responses with metadata
    */
-  async listStoredToolResponses(): Promise<string> {
+  async listStoredToolResponses(
+    options?: ListStoredToolResponsesOptions
+  ): Promise<string> {
     return executeListStoredToolResponses(
       this.storage,
       this.metadataStorage,
-      this.toolNameMap
+      this.toolNameMap,
+      options
     );
   }
 
@@ -281,9 +287,10 @@ export class ToolResponseCache {
     toolsService.addFunctions({
       [jqToolResponseDefinition.function.name]: async (
         toolCallId: string,
-        jqQuery: string
+        jqQuery: string,
+        options?: JqOptions
       ) => {
-        return await this.queryToolResponse(toolCallId, jqQuery);
+        return await this.queryToolResponse(toolCallId, jqQuery, options);
       },
       [grepToolResponseDefinition.function.name]: async (
         toolCallId: string,
@@ -298,8 +305,10 @@ export class ToolResponseCache {
       ) => {
         return await this.tailToolResponse(toolCallId, options);
       },
-      [listStoredToolResponsesDefinition.function.name]: async () => {
-        return await this.listStoredToolResponses();
+      [listStoredToolResponsesDefinition.function.name]: async (
+        options?: ListStoredToolResponsesOptions
+      ) => {
+        return await this.listStoredToolResponses(options);
       },
     });
   }

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/processors/tools/boundedToolResponse.ts

@@ -0,0 +1,49 @@
+export const DEFAULT_TOOL_RESPONSE_CHARACTERS = 20_000;
+export const MAX_TOOL_RESPONSE_CHARACTERS = 50_000;
+
+export function boundedInteger(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number
+): number {
+  return Math.min(
+    max,
+    Math.max(min, Number.isFinite(value) ? Math.floor(value as number) : fallback)
+  );
+}
+
+/** Return a bounded character page with instructions for retrieving the next page. */
+export function paginateToolResponse(
+  value: string,
+  options?: { characterOffset?: number; maxCharacters?: number },
+  label = "response"
+): string {
+  const characterOffset = boundedInteger(
+    options?.characterOffset,
+    0,
+    0,
+    Number.MAX_SAFE_INTEGER
+  );
+  const maxCharacters = boundedInteger(
+    options?.maxCharacters,
+    DEFAULT_TOOL_RESPONSE_CHARACTERS,
+    1_000,
+    MAX_TOOL_RESPONSE_CHARACTERS
+  );
+  const footerReserve = 300;
+  const contentLimit = Math.max(1, maxCharacters - footerReserve);
+  const page = value.slice(characterOffset, characterOffset + contentLimit);
+  const end = characterOffset + page.length;
+  if (characterOffset === 0 && end >= value.length) {
+    return page;
+  }
+
+  const safeLabel = label.slice(0, 200);
+  const footer =
+    end < value.length
+      ? `\n\n[${safeLabel} characters ${characterOffset}-${Math.max(characterOffset, end - 1)} of ${value.length}. Repeat with characterOffset=${end} to continue; maxCharacters=${maxCharacters}.]`
+      : `\n\n[End of ${safeLabel}; characters ${characterOffset}-${Math.max(characterOffset, end - 1)} of ${value.length}.]`;
+
+  return (page + footer).slice(0, maxCharacters);
+}