@tyvm/knowhow 0.0.106 → 0.0.108-dev.bd8f104-dev.bd8f104-dev.bd8f104

package/src/clients/gemini.ts

@@ -26,7 +26,7 @@ import {
 } from "../types";
 import { GeminiTextPricing } from "./pricing";
 import { ContextLimits } from "./contextLimits";
-import { ModelModality } from "./types";
+import { ModelModality, TokenUsage } from "./types";
 
 import {
   GenericClient,
@@ -524,10 +524,22 @@ export class GenericGeminiClient implements GenericClient {
         ? this.calculateCost(options.model, usage)
         : undefined;
 
+      // Map cachedContentTokenCount → prompt_tokens_details.cached_tokens so that
+      // base.ts can read cache hit tokens via usage.prompt_tokens_details?.cached_tokens
+      const cachedTokens = (usage as any)?.cachedContentTokenCount ?? 0;
+      const usageWithCache: TokenUsage | undefined = usage
+        ? ({
+            prompt_tokens: (usage as any).promptTokenCount ?? 0,
+            completion_tokens: (usage as any).candidatesTokenCount ?? 0,
+            total_tokens: (usage as any).totalTokenCount,
+            prompt_tokens_details: { cached_tokens: cachedTokens },
+          } as TokenUsage)
+        : undefined;
+
       return {
         choices,
         model: options.model,
-        usage,
+        usage: usageWithCache,
         usd_cost: usdCost,
       };
     } catch (error) {

package/src/clients/http.ts

@@ -264,6 +264,10 @@ export class HttpClient implements GenericClient {
             prompt_tokens: data.usage.input_tokens,
             completion_tokens: data.usage.output_tokens,
             total_tokens: data.usage.input_tokens + data.usage.output_tokens,
+            prompt_tokens_details: {
+              cached_tokens:
+                data.usage.input_tokens_details?.cached_tokens ?? 0,
+            },
           }
         : undefined;
 

package/src/clients/openai.ts

@@ -176,7 +176,14 @@ export class GenericOpenAiClient implements GenericClient {
       })),
 
       model: options.model,
-      usage: response.usage,
+      usage: response.usage ? {
+        prompt_tokens: response.usage.prompt_tokens ?? 0,
+        completion_tokens: response.usage.completion_tokens ?? 0,
+        total_tokens: response.usage.total_tokens,
+        prompt_tokens_details: {
+          cached_tokens: response.usage.prompt_tokens_details?.cached_tokens ?? 0,
+        },
+      } : undefined,
       usd_cost: usdCost,
     };
   }
@@ -300,6 +307,10 @@ export class GenericOpenAiClient implements GenericClient {
           completion_tokens: response.usage.output_tokens,
           total_tokens:
             response.usage.input_tokens + response.usage.output_tokens,
+          prompt_tokens_details: {
+            cached_tokens:
+              response.usage.input_tokens_details?.cached_tokens ?? 0,
+          },
         }
       : undefined;
 

package/src/clients/pricing/openai.ts

@@ -156,6 +156,7 @@ export const OpenAiResponsesOnlyModels: string[] = [
   OpenAiModels.GPT_54_Nano,
   OpenAiModels.GPT_54_Pro,
   OpenAiModels.GPT_55_Pro,
+  OpenAiModels.GPT_55,
   OpenAiModels.GPT_5_Pro,
   OpenAiModels.o1,
   OpenAiModels.o1_Pro,

package/src/clients/types.ts

@@ -61,6 +61,40 @@ export interface CompletionOptions {
    *  Maps to: OpenAI reasoning_effort, xAI reasoning.effort, Gemini thinkingLevel/thinkingBudget, Anthropic thinking budget.
    *  "low" = minimal thinking, "medium" = balanced, "high" = maximum reasoning */
   reasoning_effort?: "low" | "medium" | "high";
+  /**
+   * When true, hints to the client that this task is long-running and it should
+   * use a long-TTL cache where available.
+   * - Anthropic: enables the `extended-cache-ttl-2025-02-19` beta and sets
+   *   `cache_control.ttl` to 3600 (1 hour) instead of the default 5-minute ephemeral cache.
+   */
+  long_ttl_cache?: boolean;
+}
+
+/**
+ * Normalised token-usage shape that every client must return.
+ * All clients must map their provider-specific field names into this structure
+ * so that base.ts can accurately track input/output and cache utilization.
+ */
+export interface TokenUsage {
+  /** Total input/prompt tokens consumed */
+  prompt_tokens: number;
+  /** Total output/completion tokens generated */
+  completion_tokens: number;
+  /** Alternative field name for input tokens (some providers use this) */
+  input_tokens?: number;
+  /** Alternative field name for output tokens (some providers use this) */
+  output_tokens?: number;
+  /** Convenience total (prompt + completion) */
+  total_tokens?: number;
+  /** Cache details */
+  prompt_tokens_details?: {
+    /** Tokens served from the prompt cache (reduces cost) */
+    cached_tokens: number;
+  };
+  /** Anthropic-style cache write tokens */
+  cache_creation_input_tokens?: number;
+  /** Anthropic-style cache read tokens (alternative field name) */
+  cache_read_input_tokens?: number;
 }
 
 export interface CompletionResponse {
@@ -69,7 +103,7 @@ export interface CompletionResponse {
   }[];
 
   model: string;
-  usage: any;
+  usage: TokenUsage | undefined;
   usd_cost?: number;
 }
 

package/src/clients/xai.ts

@@ -99,7 +99,14 @@ export class GenericXAIClient implements GenericClient {
       })),
 
       model: options.model,
-      usage: response.usage,
+      usage: response.usage ? {
+        prompt_tokens: response.usage.prompt_tokens ?? 0,
+        completion_tokens: response.usage.completion_tokens ?? 0,
+        total_tokens: response.usage.total_tokens,
+        prompt_tokens_details: {
+          cached_tokens: response.usage.prompt_tokens_details?.cached_tokens ?? 0,
+        },
+      } : undefined,
       usd_cost: usdCost,
     };
   }
@@ -200,6 +207,9 @@ export class GenericXAIClient implements GenericClient {
           prompt_tokens: data.usage.input_tokens,
           completion_tokens: data.usage.output_tokens,
           total_tokens: data.usage.input_tokens + data.usage.output_tokens,
+          prompt_tokens_details: {
+            cached_tokens: data.usage.input_tokens_details?.cached_tokens ?? 0,
+          },
         }
       : undefined;
 

package/src/cloudWorker.ts

@@ -4,9 +4,14 @@ import { KnowhowSimpleClient, KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { loadJwt } from "./login";
 import { getConfig, updateConfig, getLanguageConfig } from "./config";
 import { services } from "./services";
-import { Language, Config } from "./types";
+import { Language, Config, McpConfig } from "./types";
 import { S3Service } from "./services/S3";
 
+export interface CloudWorkerPullOptions {
+  id: string;
+  apiUrl?: string;
+}
+
 export interface CloudWorkerOptions {
   create?: boolean;
   push?: string; // uid of existing cloud worker
@@ -330,3 +335,72 @@ export async function cloudWorker(options: CloudWorkerOptions) {
     console.log(`\n✅ Cloud worker sync complete!`);
   }
 }
+
+/**
+ * Pull the latest workerConfigJson from the cloud worker API and update the
+ * local knowhow.json config to match.
+ *
+ * This is the "pull" half of the config sync cycle.  After running this,
+ * you can reload the worker's MCPs (in-process) via the reloadConfig
+ * WebSocket message or by calling `knowhow worker` again.
+ *
+ * Merged fields from workerConfigJson:
+ *   - mcps        → overwrites config.mcps
+ *   - modules     → overwrites config.modules  (optional, only if present)
+ *   - plugins     → overwrites config.plugins  (optional, only if present)
+ *   - agents      → overwrites config.agents   (optional, only if present)
+ */
+export async function pullCloudWorkerConfig(options: CloudWorkerPullOptions) {
+  const { id, apiUrl = KNOWHOW_API_URL } = options;
+
+  // Load JWT
+  const jwt = await loadJwt();
+  if (!jwt) {
+    console.error("❌ No JWT token found. Please run 'knowhow login' first.");
+    process.exit(1);
+  }
+
+  const client = new KnowhowSimpleClient(apiUrl, jwt);
+
+  console.log(`🔄 Pulling config for cloud worker ${id}...`);
+
+  const resp = await client.getCloudWorker(id);
+  const remoteWorker = resp.data;
+
+  if (!remoteWorker) {
+    console.error(`❌ Cloud worker ${id} not found.`);
+    process.exit(1);
+  }
+
+  const remoteConfig = (remoteWorker.workerConfigJson ?? {}) as {
+    mcps?: McpConfig[];
+    modules?: string[];
+    plugins?: Config["plugins"];
+    agents?: Config["agents"];
+  };
+
+  // Load current local config
+  const localConfig = await getConfig();
+
+  // Merge remote fields into local config
+  if (remoteConfig.mcps !== undefined) {
+    localConfig.mcps = remoteConfig.mcps;
+  }
+  if (remoteConfig.modules !== undefined) {
+    localConfig.modules = remoteConfig.modules;
+  }
+  if (remoteConfig.plugins !== undefined) {
+    localConfig.plugins = remoteConfig.plugins;
+  }
+  if (remoteConfig.agents !== undefined) {
+    localConfig.agents = remoteConfig.agents;
+  }
+
+  await updateConfig(localConfig);
+
+  const mcpCount = remoteConfig.mcps?.length ?? 0;
+  console.log(`✅ Config pulled! ${mcpCount} MCP(s) now configured locally.`);
+  console.log(`   Run 'knowhow worker' or trigger reloadConfig to apply changes.`);
+
+  return { mcps: remoteConfig.mcps, modules: remoteConfig.modules };
+}

package/src/index.ts

@@ -138,6 +138,23 @@ export async function upload() {
       if (!source.remoteId) {
         throw new Error("remoteId is required for knowhow uploads");
       }
+      // Warn if the local embeddingModel differs from the one stored on the backend
+      try {
+        const remoteEmbedding = await knowhowApiClient.getOrgEmbedding(source.remoteId);
+        const localModel = config.embeddingModel || EmbeddingModels.openai.EmbeddingAda2;
+        const remoteModel = remoteEmbedding?.modelName;
+        if (remoteModel && remoteModel !== localModel) {
+          console.warn(
+            `⚠️  WARNING: Embedding model mismatch for "${remoteEmbedding.name}" (remoteId: ${source.remoteId}).\n` +
+            `   Local config.embeddingModel:  ${localModel}\n` +
+            `   Backend embedding modelName:  ${remoteModel}\n` +
+            `   Vectors generated with different models are not comparable — search results will be incorrect.\n` +
+            `   Update your config.embeddingModel to "${remoteModel}" or update the backend embedding to "${localModel}".`
+          );
+        }
+      } catch (e) {
+        // Non-fatal — don't block upload if metadata fetch fails
+      }
       const url = await knowhowApiClient.getPresignedUploadUrl(source);
       console.log("Uploading to", url);
       await AwsS3.uploadToPresignedUrl(url, source.output);

package/src/plugins/embedding.ts

@@ -20,9 +20,12 @@ export class EmbeddingPlugin extends PluginBase {
 
   constructor(context) {
     super(context);
-    
+
     // Subscribe to file:post-edit events
-    this.context.Events.on("file:post-edit", this.handleFilePostEdit.bind(this));
+    this.context.Events.on(
+      "file:post-edit",
+      this.handleFilePostEdit.bind(this)
+    );
   }
 
   async embed() {
@@ -68,10 +71,12 @@ export class EmbeddingPlugin extends PluginBase {
       this.log(`Reading entry ${entry.id}`);
     }
 
-    const contextLength = JSON.stringify(context).split(" ").length;
+    const ids = context.map((entry) => entry.id);
+
+    const contextLength = JSON.stringify(ids).split(" ").length;
     this.log(`Found ${context.length} entries. Loading ${contextLength} words`);
 
-    return `EMBEDDING PLUGIN: Our knowledgebase contains this information which can be used to answer the question:
-    ${JSON.stringify(context)}`;
+    return `EMBEDDING PLUGIN: Our knowledgebase indicates these embedding entries may be related to the question:
+    ${JSON.stringify(ids)}`;
   }
-}
+}

package/src/plugins/vim.ts

@@ -73,22 +73,11 @@ export class VimPlugin extends PluginBase {
 
   async call() {
     const vimFiles = await this.getVimFiles();
-    const fileContents = await Promise.all(
-      vimFiles.map(async (f) => {
-        const loaded = await this.getFileContents(f);
-
-        const preview =
-          loaded.content.length > 1000
-            ? loaded.content.slice(0, 1000) +
-              "... file trimmed, read file for full content"
-            : loaded.content;
-
-        return {
-          sourceFile: loaded.filePath,
-          content: loaded.content.slice(0, 1000),
-        };
-      })
-    );
+    const fileContents = vimFiles.map((f) => {
+      return {
+        sourceFile: f,
+      };
+    });
     if (fileContents.length === 0) {
       return "VIM PLUGIN: No files open in vim";
     }

package/src/services/KnowhowClient.ts

@@ -171,11 +171,9 @@ export class KnowhowSimpleClient {
       try {
         this.jwtValidated = true;
         const response = await this.me();
-
         const user = response.data.user;
         const orgs = user.orgs;
         const orgId = response.data.orgId;
-
         const currentOrg = orgs.find((org) => {
           return org.organizationId === orgId;
         });
@@ -227,6 +225,17 @@ export class KnowhowSimpleClient {
     return presignedUrl;
   }
 
+  async getOrgEmbedding(id: string) {
+    await this.checkJwt();
+    const resp = await http.get(
+      `${this.baseUrl}/api/org-embeddings/${id}`,
+      {
+        headers: this.headers,
+      }
+    );
+    return resp.data as { id: string; modelName: string; name: string; [key: string]: unknown };
+  }
+
   async updateEmbeddingMetadata(
     id: string,
     data: {
@@ -718,6 +727,17 @@ export class KnowhowSimpleClient {
     );
   }
 
+  /**
+   * Get a single cloud worker by ID
+   */
+  async getCloudWorker(id: string) {
+    await this.checkJwt();
+    return http.get<{ id: string; name: string; status: string; workerConfigJson?: Record<string, unknown> }>(
+      `${this.baseUrl}/api/cloud-workers/${id}`,
+      { headers: this.headers }
+    );
+  }
+
   /**
    * Update an existing cloud worker
    */

package/src/services/S3.ts

@@ -1,5 +1,6 @@
 import * as fs from "fs";
 import { createWriteStream, createReadStream } from "fs";
+import * as crypto from "crypto";
 import { pipeline, Readable } from "stream";
 import * as util from "util";
 
@@ -14,10 +15,19 @@ export class S3Service {
       const fileContent = fs.readFileSync(filePath);
       const fileStats = await fs.promises.stat(filePath);
 
+      // Compute SHA-256 checksum (base64) — required when presigned URL was
+      // generated with ChecksumAlgorithm: SHA256
+      const sha256Base64 = crypto
+        .createHash("sha256")
+        .update(fileContent)
+        .digest("base64");
+
       const response = await fetch(presignedUrl, {
         method: "PUT",
         headers: {
           "Content-Length": String(fileStats.size),
+          "x-amz-checksum-sha256": sha256Base64,
+          "x-amz-sdk-checksum-algorithm": "SHA256",
         },
         body: fileContent,
         // @ts-ignore

package/src/services/modules/types.ts

@@ -9,6 +9,7 @@ import { PluginService } from "../../plugins/plugins";
 import { AIClient } from "../../clients";
 import { ToolsService } from "../Tools";
 import { MediaProcessorService } from "../MediaProcessorService";
+import { TunnelHandler } from "@tyvm/knowhow-tunnel";
 
 /*
  *
@@ -53,6 +54,7 @@ export interface ModuleContext {
   Clients: AIClient;
   Tools: ToolsService;
   MediaProcessor?: MediaProcessorService;
+  Tunnel?: TunnelHandler;
 }
 
 export interface KnowhowModule {

package/src/worker.ts

@@ -6,7 +6,7 @@ import { loadJwt } from "./login";
 import { services } from "./services";
 import { PasskeySetupService } from "./workers/auth/PasskeySetup";
 import { WorkerPasskeyAuthService } from "./workers/auth/WorkerPasskeyAuth";
-import { makeUnlockTool, makeLockTool } from "./workers/tools";
+import { makeUnlockTool, makeLockTool, makeReloadConfigTool } from "./workers/tools";
 import { McpServerService } from "./services/Mcp";
 import * as allTools from "./agents/tools";
 import workerTools from "./workers/tools";
@@ -14,6 +14,7 @@ import { wait } from "./utils";
 import { getConfig, updateConfig } from "./config";
 import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { registerWorkerPath } from "./workerRegistry";
+import { ModulesService } from "./services/modules";
 
 const API_URL = KNOWHOW_API_URL;
 
@@ -264,6 +265,22 @@ export async function worker(options?: {
     console.log("🔑 Auth tools registered: unlock, lock");
   }
 
+  // Register the reloadConfig tool so agents can hot-reload MCPs/config
+  // without restarting the worker process.
+  // Uses a closure over `toolsToUse` so the tool can update it in-place.
+  const { reloadConfig, reloadConfigDefinition } = makeReloadConfigTool(
+    Mcp,
+    Tools,
+    mcpServer,
+    (newTools) => {
+      toolsToUse = newTools;
+    }
+  );
+  Tools.addFunctions({ reloadConfig });
+  toolsToUse = [...toolsToUse, reloadConfigDefinition];
+
+  console.log("🔄 reloadConfig tool registered");
+
   mcpServer.createServer(clientName, clientVersion).withTools(toolsToUse);
 
   let connected = false;
@@ -403,6 +420,33 @@ export async function worker(options?: {
             console.log(`✅ Worker ID recorded: ${parsed.workerId}`);
           }
         }
+
+        // Hot-reload: re-read config, reconnect MCPs, and rebuild the tool list
+        // without restarting the worker process.
+        if (parsed?.type === "reloadConfig") {
+          console.log("🔄 Received reloadConfig — reloading MCPs, modules and tools...");
+          try {
+            // Re-read fresh config from disk
+            const freshConfig = await getConfig();
+
+            // Close all existing MCP connections
+            await Mcp.closeAll();
+
+            // Reconnect from fresh config and re-register tools
+            await Mcp.connectToConfigured(Tools);
+
+            // Rebuild the allowed tools list from fresh config
+            const allowedToolNames = freshConfig.worker?.allowedTools ?? Tools.getToolNames();
+            toolsToUse = Tools.getToolsByNames(allowedToolNames);
+
+            // Update the MCP server with new tool list
+            mcpServer.withTools(toolsToUse);
+
+            console.log(`✅ Config reloaded: ${toolsToUse.length} tools active`);
+          } catch (err) {
+            console.error("❌ Failed to reload config:", err);
+          }
+        }
       } catch {
         // Not our message — ignore parse errors
       }
@@ -462,6 +506,16 @@ export async function worker(options?: {
         tunnelHandler = createTunnelHandler(tunnelConnection!, tunnelConfig);
         console.log("🌐 Tunnel handler initialized");
         console.log(tunnelConfig);
+
+        // Let modules that need the tunnel handler register their addons now
+        const tunnelModulesService = new ModulesService();
+        const { Agents, Embeddings, Plugins, Clients, Tools, MediaProcessor } = services();
+        tunnelModulesService.loadModulesFromConfig({
+          Agents, Embeddings, Plugins, Clients, Tools, MediaProcessor,
+          Tunnel: tunnelHandler,
+        }).catch((err) => {
+          console.error("Failed to load tunnel modules:", err);
+        });
       });
 
       tunnelConnection.on("close", (code, reason) => {
@@ -708,6 +762,16 @@ export async function tunnel(options?: {
       tunnelHandler = createTunnelHandler(tunnelConnection, tunnelConfig);
       console.log("🌐 Tunnel handler initialized");
       console.log(tunnelConfig);
+
+      // Let modules that need the tunnel handler register their addons now
+      const tunnelModulesService2 = new ModulesService();
+      const { Agents: A2, Embeddings: E2, Plugins: P2, Clients: C2, Tools: T2, MediaProcessor: MP2 } = services();
+      tunnelModulesService2.loadModulesFromConfig({
+        Agents: A2, Embeddings: E2, Plugins: P2, Clients: C2, Tools: T2, MediaProcessor: MP2,
+        Tunnel: tunnelHandler,
+      }).catch((err) => {
+        console.error("Failed to load tunnel modules:", err);
+      });
     });
 
     tunnelConnection.on("close", (code, reason) => {

package/src/workers/tools/index.ts

@@ -2,6 +2,7 @@ export * from "./listAllowedPorts";
 export * from "./getChallenge";
 export * from "./unlock";
 export * from "./lock";
+export * from "./reloadConfig";
 
 import {
   listAllowedPorts,
@@ -11,6 +12,7 @@ import {
 export { makeGetChallengeTool } from "./getChallenge";
 export { makeUnlockTool } from "./unlock";
 export { makeLockTool } from "./lock";
+export { makeReloadConfigTool } from "./reloadConfig";
 
 export default {
   tools: { listAllowedPorts },

package/src/workers/tools/reloadConfig.ts

@@ -0,0 +1,84 @@
+import { Tool } from "../../clients/types";
+import { getConfig } from "../../config";
+import { McpServerService } from "../../services/McpServer";
+import { McpService } from "../../services/Mcp";
+import { ToolsService } from "../../services/Tools";
+
+export interface ReloadConfigResult {
+  success: boolean;
+  toolCount: number;
+  mcpCount: number;
+  message: string;
+}
+
+/**
+ * Factory that creates the reloadConfig tool with access to runtime services.
+ * The tool re-reads the config from disk, reconnects all MCPs, and rebuilds
+ * the active tool list — the same logic as the WebSocket reloadConfig handler.
+ *
+ * Typical usage after pulling updated config from the cloud worker API:
+ *   1. execCommand("knowhow cloudworker --pull <cloudWorkerId>")
+ *   2. reloadConfig()
+ */
+export function makeReloadConfigTool(
+  Mcp: McpService,
+  Tools: ToolsService,
+  mcpServer: McpServerService,
+  setToolsToUse: (tools: ReturnType<typeof Tools.getToolsByNames>) => void
+) {
+  const reloadConfig = async (): Promise<ReloadConfigResult> => {
+    try {
+      // Re-read fresh config from disk
+      const freshConfig = await getConfig();
+
+      // Close all existing MCP connections
+      await Mcp.closeAll();
+
+      // Reconnect from fresh config and re-register tools
+      await Mcp.connectToConfigured(Tools);
+
+      // Rebuild the allowed tools list from fresh config
+      const allowedToolNames =
+        freshConfig.worker?.allowedTools ?? Tools.getToolNames();
+      const newToolsToUse = Tools.getToolsByNames(allowedToolNames);
+      setToolsToUse(newToolsToUse);
+
+      // Update the MCP server with the new tool list
+      mcpServer.withTools(newToolsToUse);
+
+      const mcpCount = freshConfig.mcps?.length ?? 0;
+
+      return {
+        success: true,
+        toolCount: newToolsToUse.length,
+        mcpCount,
+        message: `Config reloaded: ${newToolsToUse.length} tools active, ${mcpCount} MCP(s) configured`,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        success: false,
+        toolCount: 0,
+        mcpCount: 0,
+        message: `Failed to reload config: ${message}`,
+      };
+    }
+  };
+
+  const reloadConfigDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "reloadConfig",
+      description:
+        "Reload the worker config from disk, reconnect all MCPs, and rebuild the active tool list. " +
+        "Call this after running `knowhow cloudworker --pull <id>` to apply updated MCPs without restarting the worker.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  };
+
+  return { reloadConfig, reloadConfigDefinition };
+}

package/tests/clients/AIClient.test.ts

@@ -42,7 +42,7 @@ class FakeClient implements GenericClient {
         },
       ],
       model: options.model,
-      usage: { total_tokens: 100 },
+      usage: { prompt_tokens: 50, completion_tokens: 50, total_tokens: 100 },
     };
   }