@tyvm/knowhow 0.0.107 → 0.0.108-dev.879609c

package/src/clients/anthropic.ts

@@ -40,11 +40,11 @@ export class GenericAnthropicClient implements GenericClient {
     });
   }
 
-  handleToolCaching(tools: Anthropic.Tool[]) {
+  handleToolCaching(tools: Anthropic.Tool[], longTtl = false) {
     const lastTool = tools[tools.length - 1];
 
     if (lastTool) {
-      lastTool.cache_control = { type: "ephemeral" };
+      lastTool.cache_control = longTtl ? { type: "ephemeral", ttl: "1h" } as any : { type: "ephemeral" };
     }
   }
 
@@ -94,7 +94,7 @@ export class GenericAnthropicClient implements GenericClient {
     return cleaned;
   }
 
-  transformTools(tools?: Tool[]): Anthropic.Tool[] {
+  transformTools(tools?: Tool[], longTtl = false): Anthropic.Tool[] {
     if (!tools) {
       return [];
     }
@@ -104,7 +104,7 @@ export class GenericAnthropicClient implements GenericClient {
       input_schema: this.cleanSchemaForAnthropic(tool.function.parameters) as any,
     }));
 
-    this.handleToolCaching(transformed);
+    this.handleToolCaching(transformed, longTtl);
 
     return transformed;
   }
@@ -153,16 +153,16 @@ export class GenericAnthropicClient implements GenericClient {
     return messages;
   }
 
-  cacheLastContent(message: MessageParam) {
+  cacheLastContent(message: MessageParam, longTtl = false) {
     if (Array.isArray(message.content)) {
       const lastMessage = message.content[message.content.length - 1];
       if (
         lastMessage.type !== "thinking" &&
         lastMessage.type !== "redacted_thinking"
       ) {
-        lastMessage.cache_control = {
-          type: "ephemeral",
-        };
+        lastMessage.cache_control = longTtl
+          ? ({ type: "ephemeral", ttl: "1h" } as any)
+          : { type: "ephemeral" };
       }
     }
   }
@@ -179,7 +179,7 @@ export class GenericAnthropicClient implements GenericClient {
     }
   }
 
-  handleMessageCaching(groupedMessages: MessageParam[]) {
+  handleMessageCaching(groupedMessages: MessageParam[], longTtl = false) {
     this.handleClearingCache(groupedMessages);
 
     // find the last two messages and mark them as ephemeral
@@ -189,7 +189,7 @@ export class GenericAnthropicClient implements GenericClient {
 
     for (const m of lastTwoUserMessages) {
       if (Array.isArray(m.content)) {
-        this.cacheLastContent(m);
+        this.cacheLastContent(m, longTtl);
       }
     }
   }
@@ -203,7 +203,7 @@ export class GenericAnthropicClient implements GenericClient {
     }
   }
 
-  transformMessages(messages: Message[]): MessageParam[] {
+  transformMessages(messages: Message[], longTtl = false): MessageParam[] {
     const toolCalls = messages.flatMap((msg) => msg.tool_calls || []);
     const claudeMessages: MessageParam[] = messages
       .filter((msg) => msg.role !== "system")
@@ -302,7 +302,7 @@ export class GenericAnthropicClient implements GenericClient {
 
     const groupedMessages = this.combineMessages(claudeMessages);
 
-    this.handleMessageCaching(groupedMessages);
+    this.handleMessageCaching(groupedMessages, longTtl);
 
     return groupedMessages;
   }
@@ -349,14 +349,15 @@ export class GenericAnthropicClient implements GenericClient {
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    const longTtl = !!options.long_ttl_cache;
     const systemMessage = options.messages
       .filter((msg) => msg.role === "system")
       .map((msg) => msg.content || "")
       .join("\n");
 
-    const claudeMessages = this.transformMessages(options.messages);
+    const claudeMessages = this.transformMessages(options.messages, longTtl);
 
-    const tools = this.transformTools(options.tools);
+    const tools = this.transformTools(options.tools, longTtl);
     try {
       const response = await this.client.messages.create({
         model: options.model,
@@ -365,7 +366,7 @@ export class GenericAnthropicClient implements GenericClient {
           ? [
               {
                 text: systemMessage,
-                cache_control: { type: "ephemeral" },
+                cache_control: longTtl ? ({ type: "ephemeral", ttl: "1h" } as any) : { type: "ephemeral" },
                 type: "text",
               },
             ]
@@ -413,6 +414,8 @@ export class GenericAnthropicClient implements GenericClient {
 
         model: options.model,
         usage: response.usage ? {
+          input_tokens: response.usage.input_tokens ?? 0,
+          output_tokens: response.usage.output_tokens ?? 0,
           prompt_tokens: response.usage.input_tokens ?? 0,
           completion_tokens: response.usage.output_tokens ?? 0,
           total_tokens: (response.usage.input_tokens ?? 0) + (response.usage.output_tokens ?? 0),
@@ -422,7 +425,7 @@ export class GenericAnthropicClient implements GenericClient {
         usd_cost: this.calculateCost(options.model, response.usage),
       };
     } catch (err) {
-      if ("headers" in err && err.headers["x-should-retry"] === "true") {
+      if ("headers" in err && err.headers?.["x-should-retry"] === "true") {
         console.warn("Retrying failed request", err);
         await wait(2500);
         return this.createChatCompletion(options);

package/src/clients/types.ts

@@ -1,4 +1,10 @@
-export type ModelModality = "completion" | "embedding" | "image" | "audio" | "video" | "transcription";
+export type ModelModality =
+  | "completion"
+  | "embedding"
+  | "image"
+  | "audio"
+  | "video"
+  | "transcription";
 
 export type MessageContent =
   | { type: "text"; text: string }
@@ -8,7 +14,7 @@ export type MessageContent =
 
 export interface Message {
   role: "system" | "user" | "assistant" | "tool";
-  content?: string | MessageContent[];
+  content?: string | MessageContent[] | null;
 
   name?: string;
   tool_call_id?: string;
@@ -16,7 +22,7 @@ export interface Message {
 }
 
 export interface OutputMessage extends Message {
-  content: string;
+  content?: string | null;
 }
 
 export interface ToolProp {
@@ -61,6 +67,13 @@ 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;
 }
 
 /**
@@ -73,6 +86,10 @@ export interface TokenUsage {
   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 */
@@ -290,7 +307,9 @@ export interface GenericClient {
    * When modality is provided, return only models for that modality (static list).
    * When omitted, return ALL models (backward compat — may do a live API call).
    */
-  getModels(modality?: ModelModality): Promise<{ id: string; modality?: ModelModality[] }[]>;
+  getModels(
+    modality?: ModelModality
+  ): Promise<{ id: string; modality?: ModelModality[] }[]>;
   /**
    * Returns the context window limit and compression threshold for a given model,
    * or undefined if the model is not known to this client.

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

@@ -382,7 +382,7 @@ export class JsonCompressor {
             i + currentChunk.length - 1
           }]\nPreview: ${chunkString.substring(0, 100)}...\n[Use ${
             this.toolName
-          } tool with key "${key}" to retrieve this chunk]`;
+          } tool with key "${key}" to retrieve this chunk]\n[TIP: try jqToolResponse,grepToolResponse,tailToolResponse to filter/search/map without repeated ${this.toolName} calls - especially useful for JSON data]`;
           finalArray.unshift(stub); // Add stub to the start of our final result.
 
           currentChunk = [];
@@ -453,7 +453,7 @@ export class JsonCompressor {
           result
         ).join(", ")}\nPreview: ${objectAsString.substring(0, 200)}...\n[Use ${
           this.toolName
-        } tool with key "${key}" to retrieve full content]`;
+        } tool with key "${key}" to retrieve full content]\n[TIP: try jqToolResponse,grepToolResponse,tailToolResponse to filter/search/map without repeated ${this.toolName} calls - especially useful for JSON data]`;
       }
       return result;
     }
@@ -486,7 +486,7 @@ export class JsonCompressor {
           200
         )}...\n[Use ${
           this.toolName
-        } tool with key "${key}" to retrieve full content]`;
+        } tool with key "${key}" to retrieve full content]\n[TIP: try jqToolResponse,grepToolResponse,tailToolResponse to filter/search/map without repeated ${this.toolName} calls - especially useful for JSON data]`;
       }
       return obj;
     }

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