@tyvm/knowhow 0.0.127 → 0.0.129

package/src/processors/MinimalToolsMessageProcessor.ts

@@ -0,0 +1,113 @@
+import { Message, ToolCall } from "../clients/types";
+import { MessageProcessorFunction } from "../services/MessageProcessor";
+
+/**
+ * MinimalToolsMessageProcessor
+ *
+ * Works with MinimalToolsService to unwrap `callTool(name, args)` invocations
+ * in the message history, rewriting them as if the real tool had been called
+ * directly.
+ *
+ * This is registered on the `pre_tools` lifecycle so it runs right before tool
+ * calls are dispatched. It rewrites the last assistant message's tool_calls so
+ * that:
+ *   callTool({ name: "readFile", args: { filePath: "..." } })
+ * becomes:
+ *   readFile({ filePath: "..." })
+ *
+ * This means:
+ * 1. The `tools:` array sent to the AI never needs to change (cache stable).
+ * 2. The agent terminates correctly when callTool("finalAnswer", ...) is called,
+ *    because after transformation the required tool name matches.
+ * 3. The conversation history looks clean — the model sees native tool calls in
+ *    subsequent turns rather than nested callTool wrappers.
+ */
+export class MinimalToolsMessageProcessor {
+  /**
+   * Unwraps a single callTool ToolCall into the real underlying ToolCall.
+   * Returns null if this is not a callTool invocation.
+   */
+  private unwrapCallTool(toolCall: ToolCall): ToolCall | null {
+    if (toolCall.function.name !== "callTool") {
+      return null;
+    }
+
+    let parsed: { name?: string; args?: Record<string, any> };
+    try {
+      parsed =
+        typeof toolCall.function.arguments === "string"
+          ? JSON.parse(toolCall.function.arguments)
+          : toolCall.function.arguments;
+    } catch {
+      return null;
+    }
+
+    const { name, args } = parsed;
+    if (!name || typeof name !== "string") {
+      return null;
+    }
+
+    return {
+      id: toolCall.id,
+      type: "function",
+      function: {
+        name,
+        arguments: JSON.stringify(args ?? {}),
+      },
+    };
+  }
+
+  /**
+   * Processes the modified messages array in-place:
+   * - Finds assistant messages whose tool_calls contain callTool invocations.
+   * - Replaces those callTool entries with the real underlying tool calls.
+   *
+   * Only the most-recent assistant message (the one just added by the AI) is
+   * rewritten — older messages are left untouched so caching is not affected.
+   */
+  private processMessages(
+    _originalMessages: Message[],
+    modifiedMessages: Message[]
+  ): void {
+    // Walk backwards to find the last assistant message with tool_calls
+    for (let i = modifiedMessages.length - 1; i >= 0; i--) {
+      const msg = modifiedMessages[i];
+      if (msg.role !== "assistant" || !msg.tool_calls?.length) {
+        continue;
+      }
+
+      let didUnwrap = false;
+      const newToolCalls: ToolCall[] = msg.tool_calls.map((tc) => {
+        const unwrapped = this.unwrapCallTool(tc);
+        if (unwrapped) {
+          didUnwrap = true;
+          return unwrapped;
+        }
+        return tc;
+      });
+
+      if (didUnwrap) {
+        msg.tool_calls = newToolCalls;
+      }
+
+      // Only process the last assistant message
+      break;
+    }
+  }
+
+  /**
+   * Returns a MessageProcessorFunction suitable for registering on the
+   * `pre_tools` lifecycle of a MessageProcessor.
+   */
+  createProcessor(): MessageProcessorFunction {
+    return (
+      originalMessages: Message[],
+      modifiedMessages: Message[]
+    ): void => {
+      this.processMessages(originalMessages, modifiedMessages);
+    };
+  }
+}
+
+export const globalMinimalToolsMessageProcessor =
+  new MinimalToolsMessageProcessor();

package/src/processors/TokenCompressor.ts

@@ -155,14 +155,26 @@ export class TokenCompressor implements JsonCompressorStorage {
    * Check if content is already compressed
    */
   private isAlreadyCompressed(content: string): boolean {
-    // Check for compressed string markers
-    if (content.includes("[COMPRESSED_STRING")) {
+    // Check for a compressed-string marker, but ONLY when the content *starts*
+    // with it. Compressor output always begins with "[COMPRESSED_STRING ...".
+    // A naive `.includes()` produced false positives for large payloads (e.g. a
+    // usage.json / message-history dump) that merely CONTAIN that substring deep
+    // inside their nested data — those files were left completely uncompressed
+    // because this guard incorrectly reported them as already compressed.
+    if (content.trimStart().startsWith("[COMPRESSED_STRING")) {
       return true;
     }
 
     // Check for compressed JSON structure with schema key
+    // Only treat this as compressed when `_schema_key` is an actual TOP-LEVEL
+    // key of the parsed object — not merely present somewhere in the string.
     const parsed = this.tryParseJson(content);
-    if (parsed && parsed._schema_key && typeof parsed._schema_key === "string") {
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed) &&
+      typeof parsed._schema_key === "string"
+    ) {
       return true;
     }
 
@@ -296,7 +308,12 @@ export class TokenCompressor implements JsonCompressorStorage {
     return async (originalMessages: Message[], modifiedMessages: Message[]) => {
       // Find the index of the last assistant message so we only compress
       // the most recent batch of tool responses (after the last agent output).
-      // This prevents re-compressing already-cached historical messages.
+      // This prevents re-compressing already-cached historical messages, which
+      // would break prompt caching. Newly-added tool responses (the "current
+      // batch") are the ones that need compressing before they reach the model,
+      // and they appear after the last assistant message at the moment this
+      // processor runs (post_tools / pre_call), when the fresh tool response is
+      // still the tail of the message list.
       let lastAssistantIndex = -1;
       for (let i = modifiedMessages.length - 1; i >= 0; i--) {
         if (modifiedMessages[i].role === "assistant") {

package/src/processors/index.ts

@@ -1,7 +1,13 @@
 export { Base64ImageProcessor } from "./Base64ImageDetector";
 export { CustomVariables } from "./CustomVariables";
 export { TokenCompressor } from "./TokenCompressor";
-export { JsonCompressor, JsonSchema, CompressionMetadata, JsonCompressorStorage } from "./JsonCompressor";
+export {
+  JsonCompressor,
+  JsonSchema,
+  CompressionMetadata,
+  JsonCompressorStorage,
+} from "./JsonCompressor";
 export { ToolResponseCache } from "./ToolResponseCache";
 export { XmlToolCallProcessor } from "./XmlToolCallProcessor";
 export { HarmonyToolProcessor } from "./HarmonyToolProcessor";
+export { MinimalToolsMessageProcessor } from "./MinimalToolsMessageProcessor";

package/src/services/AgentSyncFs.ts

@@ -33,6 +33,7 @@ export class AgentSyncFs {
   private agent: BaseAgent | undefined;
   private threadUpdateHandler: ((...args: any[]) => void) | undefined;
   private doneHandler: ((...args: any[]) => void) | undefined;
+  private tokenUsageHandler: ((...args: any[]) => void) | undefined;
   /**
    * Tracks the most recent in-flight filesystem metadata update.
    * The done handler awaits this before finalizing, preventing a race where
@@ -118,6 +119,33 @@ export class AgentSyncFs {
     }
   }
 
+  /**
+   * Append a token usage entry (including the full message chain sent for
+   * 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.
+   */
+  private async appendUsageEntry(entry: any): Promise<void> {
+    if (!this.taskPath) return;
+
+    try {
+      const usagePath = path.join(this.taskPath, "usage.json");
+      let entries: any[] = [];
+
+      try {
+        const existingData = await fs.readFile(usagePath, "utf8");
+        entries = JSON.parse(existingData);
+      } catch {
+        // File doesn't exist or is invalid, start fresh
+      }
+
+      entries.push(entry);
+      await fs.writeFile(usagePath, JSON.stringify(entries, null, 2), "utf8");
+    } catch (error) {
+      console.error(`❌ Failed to append usage entry:`, error);
+    }
+  }
+
   /**
    * Update metadata file with current agent state
    */
@@ -352,6 +380,20 @@ export class AgentSyncFs {
       this.threadUpdateHandler
     );
 
+    // Listen to token usage events to record per-call usage + message chain
+    // (store reference for cleanup). This is written to usage.json so that
+    // cache-hit/cache-miss issues can be debugged by comparing the message
+    // chain and usage values sent/received on consecutive AI calls.
+    this.tokenUsageHandler = (usage: any) => {
+      this.appendUsageEntry(usage).catch((error) => {
+        console.error(`❌ Error recording token usage:`, error);
+      });
+    };
+    agent.agentEvents.on(
+      agent.eventTypes.tokenUsage,
+      this.tokenUsageHandler
+    );
+
     // Listen to completion event to finalize task (store reference for cleanup)
     this.doneHandler = (result: string) => {
       if (!this.taskId) {
@@ -495,6 +537,13 @@ export class AgentSyncFs {
         );
         this.threadUpdateHandler = undefined;
       }
+      if (this.tokenUsageHandler) {
+        this.agent.agentEvents.removeListener(
+          this.agent.eventTypes.tokenUsage,
+          this.tokenUsageHandler
+        );
+        this.tokenUsageHandler = undefined;
+      }
       if (this.doneHandler) {
         this.agent.agentEvents.removeListener(
           this.agent.eventTypes.done,

package/src/services/AgentSyncKnowhowWeb.ts

@@ -89,7 +89,7 @@ export class AgentSyncKnowhowWeb {
     try {
       await this.client.updateChatTask(knowhowTaskId, {
         threads: agent.getThreads(),
-        totalCostUsd: agent.getTotalCostUsd(),
+        totalUsdCost: agent.getTotalCostUsd(),
         inProgress,
         ...(result ? { result } : {}),
       });

package/src/services/KnowhowClient.ts

@@ -61,7 +61,7 @@ export interface CreateMessageTaskResponse {
 
 export interface UpdateOrgTaskRequest {
   threads: Message[][];
-  totalCostUsd: number;
+  totalUsdCost: number;
   inProgress: boolean;
   result?: string;
 }

package/src/services/LazyToolsService.ts

@@ -9,6 +9,18 @@ import {
 } from "../agents/tools/lazy";
 import { definitions } from "../agents/tools/lazy/definitions";
 
+/*
+ *
+ * This ToolService design allows an agent to start with a few enabled tools,
+ * search and enable additional tools
+ *
+ * One drawback: enabling a tool will bust the cache, causing you to have to pay extra after enabling new tools
+ * Benefit: for providers with limits on how many tools you can support, this tool service allows you to have the minimal set of tools you need to use in the tools array. Smaller context usage
+ *
+ * In a longer running session, where the agent's tools accumulate over multiple interactions, the cache busting is minimized
+ * In web sessions where you get a new ToolService each interaction, then the cache busting is going to happen with each enable
+ *
+ */
 export class LazyToolsService extends ToolsService {
   private allTools: Tool[] = [];
   // Start with lazy tools enabled by default

package/src/services/MinimalToolsService.ts

@@ -0,0 +1,167 @@
+import { ToolsService, ToolContext } from "./Tools";
+import { Tool, ToolCall } from "../clients/types";
+import { callTool } from "../agents/tools/minimal/callTool";
+import { inspectTools } from "../agents/tools/minimal/inspectTools";
+import { minimalDefinitions } from "../agents/tools/minimal/definitions";
+import { finalAnswer } from "../agents/tools/finalAnswer";
+import { includedTools } from "../agents/tools/list";
+
+/*
+ * MinimalToolsService
+ *
+ * A cache-stable ToolService: the `tools:` array sent to the AI is always the
+ * same small set of base tools (callTool, inspectTools, finalAnswer + any
+ * explicitly registered base tools). All other tools live in `allTools` and
+ * are callable via callTool(name, args).
+ *
+ * Benefits over LazyToolsService:
+ * - The `tools:` array NEVER changes during a session → zero cache busts from tool changes.
+ * - Works on all providers and older models (no provider-specific defer_loading needed).
+ * - Agents discover tools via inspectTools() and call them via callTool().
+ */
+export class MinimalToolsService extends ToolsService {
+  /** Full catalog of every registered tool (base + extended). */
+  private allToolsCatalog: Tool[] = [];
+
+  constructor(context?: ToolContext) {
+    super(context);
+    this.registerMinimalTools();
+  }
+
+  /**
+   * Registers the immutable base tools.
+   * These are the only tools that ever appear in the `tools:` array.
+   */
+  private registerMinimalTools(): void {
+    // finalAnswer definition is sourced from the included tools list
+    const finalAnswerDef = includedTools.find(
+      (t) => t.function.name === "finalAnswer"
+    );
+
+    const baseDefs: Tool[] = [
+      ...(finalAnswerDef ? [finalAnswerDef as Tool] : []),
+      ...minimalDefinitions,
+    ];
+
+    // Add base tool defs to both catalogs
+    this.allToolsCatalog.push(...baseDefs);
+    super.addTools(baseDefs);
+
+    // Register implementations
+    this.addFunctions({
+      finalAnswer: finalAnswer.bind(this),
+      callTool: callTool.bind(this),
+      inspectTools: inspectTools.bind(this),
+    });
+  }
+
+  /**
+   * Override addTools so that newly-registered tools go into the full catalog
+   * but NOT into the visible `tools` array (which stays stable).
+   */
+  addTools(tools: Tool[]): void {
+    const existingNames = this.allToolsCatalog.map((t) => t.function.name);
+    const newTools = tools.filter(
+      (t) => !existingNames.includes(t.function.name)
+    );
+    this.allToolsCatalog.push(...newTools);
+    // Do NOT call super.addTools() — base tools array stays frozen.
+  }
+
+  addTool(tool: Tool): void {
+    this.addTools([tool]);
+  }
+
+  /**
+   * Returns only the stable base tools (what gets sent in `tools:` to the AI).
+   */
+  getTools(): Tool[] {
+    return super.getTools();
+  }
+
+  /**
+   * Returns every tool in the catalog (base + extended). Used by callTool /
+   * inspectTools for dispatching and schema lookup.
+   */
+  getAllTools(): Tool[] {
+    return this.allToolsCatalog;
+  }
+
+  /**
+   * Calls a tool by its resolved name, bypassing the enabled-tools check that
+   * the base class applies. Used internally by the callTool dispatch function.
+   * Returns the raw functionResp (unwrapped), used by the callTool meta-tool.
+   */
+  async callToolByName(
+    toolCall: ToolCall,
+    resolvedName: string
+  ): Promise<any> {
+    const result = await this.dispatchToTool(toolCall, resolvedName);
+    return result.functionResp;
+  }
+
+  /**
+   * Shared dispatch logic: temporarily surfaces the target tool (if it's not
+   * already visible) so the base ToolsService.callTool can find its
+   * definition and implementation, then restores the visible set.
+   * Used both by direct calls (agent calls the tool by its real name) and by
+   * the callTool meta-tool (agent calls callTool({ name, args })).
+   */
+  private async dispatchToTool(toolCall: ToolCall, resolvedName: string) {
+    // Temporarily surface the target tool in the visible list so base
+    // ToolsService.callTool can find its definition, then restore state.
+    const alreadyVisible = super
+      .getTools()
+      .some((t) => t.function.name === resolvedName);
+
+    if (!alreadyVisible) {
+      const toolDef = this.allToolsCatalog.find(
+        (t) => t.function.name === resolvedName
+      );
+      if (toolDef) {
+        super.addTools([toolDef]);
+      }
+    }
+
+    const result = await super.callTool(toolCall, [resolvedName]);
+
+    // Remove the temporarily-added tool to keep the visible set stable
+    if (!alreadyVisible) {
+      this.tools = this.tools.filter((t) => t.function.name !== resolvedName);
+    }
+
+    return result;
+  }
+
+  /**
+   * Delegates to the full catalog for resolution, then runs via callToolByName.
+   */
+  async callTool(toolCall: ToolCall, enabledTools?: string[]): Promise<any> {
+    const functionName = toolCall.function.name;
+
+    // Base tools (callTool, inspectTools, finalAnswer) → standard dispatch
+    const isBaseTool = super
+      .getTools()
+      .some((t) => t.function.name === functionName);
+
+    if (isBaseTool) {
+      return super.callTool(toolCall, this.getToolNames());
+    }
+
+    // Extended tools: called directly by name (not via the callTool meta-tool).
+    // These live only in allToolsCatalog, not in the frozen visible `tools`
+    // array, so we must temporarily surface them the same way callToolByName
+    // does, otherwise base ToolsService.getTool() won't find the definition
+    // and will throw "Tool ... not found" even though it's a registered tool.
+    const existsInCatalog = this.allToolsCatalog.some(
+      (t) => t.function.name === functionName
+    );
+
+    if (existsInCatalog) {
+      return this.dispatchToTool(toolCall, functionName);
+    }
+
+    // Not found anywhere - let the base class produce the standard error.
+    return super.callTool(toolCall, [functionName]);
+  }
+}

package/src/services/Tools.ts

@@ -25,6 +25,15 @@ export interface ToolContext {
   metadata?: { [key: string]: any };
 }
 
+/*
+ *
+ * This ToolService design allows an agent to start with every tool
+ *
+ * Drawbacks:
+ * some providers have limits on how many tools you can use
+ * larger context bloat from having every tool defined in system prompt
+ *
+ */
 export class ToolsService {
   private context: ToolContext = {};
 

package/src/services/index.ts

@@ -24,6 +24,7 @@ export * from "./EmbeddingsService";
 export * from "./S3";
 export * from "./Tools";
 export * from "./LazyToolsService";
+export * from "./MinimalToolsService";
 export * as MCP from "./Mcp";
 export * from "./EmbeddingService";
 export * from "./DockerService";

package/src/worker.ts

@@ -225,9 +225,16 @@ export async function worker(options?: {
     console.log(
       "Worker tools configured! Update knowhow.json to adjust which tools are allowed by the worker."
     );
+    console.log(
+      "Tunnel is disabled by default. Set worker.tunnel.enabled = true in knowhow.json to enable it."
+    );
     config.worker = {
       ...config.worker,
       allowedTools: Tools.getToolNames(),
+      tunnel: {
+        enabled: false,
+        ...config.worker?.tunnel,
+      },
     };
     await updateConfig(config);
     return;

package/tests/processors/TokenCompressor.test.ts

@@ -83,6 +83,51 @@ describe("TokenCompressor", () => {
       expect(parsed.smallProp).toBe("small"); // Should remain unchanged
       expect(parsed.largeProp).toContain("[COMPRESSED_JSON_PROPERTY"); // Should be compressed
     });
+
+    it("should compress large content that merely CONTAINS a compression marker deep inside (regression)", () => {
+      // Regression for the false-positive in isAlreadyCompressed(): a large
+      // payload (e.g. a usage.json / message-history dump) whose body contains
+      // the substring "[COMPRESSED_STRING" deep inside its nested data was
+      // incorrectly treated as already-compressed and returned uncompressed,
+      // letting 1MB+ raw tool responses flow into createCompletion untouched.
+      const nestedMarker =
+        '[COMPRESSED_STRING - 10155 tokens in 3 chunks]\\nKey: compressed_abc123';
+      // Build a big JSON array whose entries embed the marker far from the start.
+      const entry = JSON.stringify({
+        role: "tool",
+        name: "readFile",
+        content: nestedMarker,
+        filler: "z".repeat(500),
+      });
+      const bigContent = "[" + new Array(200).fill(entry).join(",") + "]";
+
+      // Sanity: the raw content contains the marker but is NOT at the start.
+      expect(bigContent.includes("[COMPRESSED_STRING")).toBe(true);
+      expect(bigContent.trimStart().startsWith("[COMPRESSED_STRING")).toBe(false);
+
+      const result = tokenCompressor.compressContent(bigContent);
+
+      // It MUST actually get compressed, not returned untouched.
+      expect(result.length).toBeLessThan(bigContent.length);
+    });
+
+    it("should NOT recompress content that genuinely starts with a compression marker", () => {
+      // Idempotency: real compressor output begins with "[COMPRESSED_STRING".
+      const alreadyCompressed =
+        "[COMPRESSED_STRING - 999 tokens in 2 chunks]\nKey: compressed_xyz\nPath: \nPreview: ...";
+      const result = tokenCompressor.compressContent(alreadyCompressed);
+      expect(result).toBe(alreadyCompressed);
+    });
+
+    it("should NOT recompress JSON whose top-level _schema_key marks it compressed", () => {
+      // Idempotency: JSON-compressed output carries a top-level _schema_key.
+      const compressedJson = JSON.stringify({
+        _schema_key: "compressed_schema_1",
+        data: "x".repeat(40000),
+      });
+      const result = tokenCompressor.compressContent(compressedJson);
+      expect(result).toBe(compressedJson);
+    });
   });
 
   describe("compressStringInChunks", () => {