@tyvm/knowhow 0.0.109 → 0.0.110

package/src/fileSync.ts

@@ -6,7 +6,7 @@ import { loadJwt } from "./login";
 import { getConfig } from "./config";
 import { services } from "./services";
 import { S3Service } from "./services/S3";
-import { getHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote, isLocalFileMatchingDownloadHash, saveDownloadHash } from "./hashes";
+import { getHashes, saveHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote, isLocalFileMatchingDownloadHash, saveDownloadHash } from "./hashes";
 
 export const DEFAULT_BATCH_SIZE = 5;
 
@@ -165,7 +165,8 @@ export async function downloadFile(
   s3Service: S3Service,
   remotePath: string,
   localPath: string,
-  dryRun: boolean
+  dryRun: boolean,
+  hashes?: any
 ): Promise<void> {
   console.log(`⬇️  Downloading ${remotePath} → ${localPath}`);
 
@@ -176,8 +177,7 @@ export async function downloadFile(
 
   try {
     // Fast-path: check stored download hash before hitting the API
-    const hashes = await getHashes();
-    if (await isLocalFileMatchingDownloadHash(localPath, hashes)) {
+    if (hashes && await isLocalFileMatchingDownloadHash(localPath, hashes)) {
       console.log(`   ✓ Skipping ${localPath} (matches stored download hash)`);
       return;
     }
@@ -189,7 +189,7 @@ export async function downloadFile(
     if (isLocalFileMatchingRemote(localPath, checksumSHA256)) {
       console.log(`   ✓ Skipping ${localPath} (matches remote checksum)`);
       // Store the hash so future syncs can skip without hitting the API
-      await saveDownloadHash(localPath);
+      await saveDownloadHash(localPath, hashes);
       return;
     }
 
@@ -203,7 +203,7 @@ export async function downloadFile(
     await s3Service.downloadFromPresignedUrl(downloadUrl, localPath);
 
     // Save download hash so we can skip unchanged files next time
-    await saveDownloadHash(localPath);
+    await saveDownloadHash(localPath, hashes);
 
     // Get file size for logging
     const stats = fs.statSync(localPath);
@@ -221,7 +221,8 @@ export async function uploadFile(
   s3Service: S3Service,
   remotePath: string,
   localPath: string,
-  dryRun: boolean
+  dryRun: boolean,
+  hashes?: any
 ): Promise<void> {
   console.log(`⬆️  Uploading ${localPath} → ${remotePath}`);
 
@@ -237,8 +238,7 @@ export async function uploadFile(
   }
 
   // Skip upload if file hasn't changed since last upload
-  const hashes = await getHashes();
-  const changed = await hasFileChangedSinceUpload(localPath, hashes);
+  const changed = hashes ? await hasFileChangedSinceUpload(localPath, hashes) : true;
   if (!changed) {
     console.log(`   ✓ Skipping ${localPath} (unchanged since last upload)`);
     return;
@@ -254,7 +254,7 @@ export async function uploadFile(
   await client.markOrgFileUploadComplete(remotePath);
 
   // Save upload hash so we can skip unchanged files next time
-  await saveUploadHash(localPath);
+  await saveUploadHash(localPath, hashes);
 
   const stats = fs.statSync(localPath);
   console.log(`   ✓ Uploaded ${stats.size} bytes`);
@@ -276,6 +276,8 @@ export async function uploadDirectory(
 
   console.log(`⬆️  Uploading directory ${localDir} → ${remoteDir}`);
 
+  const hashes = await getHashes();
+
   if (!fs.existsSync(localDir)) {
     console.warn(`   ⚠️  Local directory not found: ${localDir}`);
     return 0;
@@ -295,7 +297,7 @@ export async function uploadDirectory(
     const localFilePath = localDir + relFile;
     const remoteFilePath = remoteDir + relFile;
     try {
-      await uploadFile(client, s3Service, remoteFilePath, localFilePath, dryRun);
+      await uploadFile(client, s3Service, remoteFilePath, localFilePath, dryRun, hashes);
       return 1;
     } catch (error) {
       console.error(
@@ -306,6 +308,8 @@ export async function uploadDirectory(
   });
 
   const counts = await batchRun(tasks);
+  await saveHashes(hashes);
+
   return counts.reduce((sum, n) => sum + n, 0);
 }
 
@@ -325,6 +329,8 @@ export async function downloadDirectory(
 
   console.log(`⬇️  Downloading directory ${remoteDir} → ${localDir}`);
 
+  const hashes = await getHashes();
+
   // List all org files and find those in the remote directory
   const response = await client.listOrgFiles();
   const allFiles = response.data;
@@ -352,10 +358,12 @@ export async function downloadDirectory(
     // Strip the base remote dir prefix to get relative path
     const relativePath = fullRemotePath.slice(remoteDir.length);
     const localFilePath = localDir + relativePath;
-    await downloadFile(client, s3Service, fullRemotePath, localFilePath, dryRun);
+    await downloadFile(client, s3Service, fullRemotePath, localFilePath, dryRun, hashes);
     return 1;
   });
 
   const counts = await batchRun(tasks);
+  await saveHashes(hashes);
+
   return counts.reduce((sum, n) => sum + n, 0);
 }

package/src/hashes.ts

@@ -1,16 +1,35 @@
 import fs from "fs";
 import * as crypto from "crypto";
 import { Hashes } from "./types";
-import { readFile, writeFile } from "./utils";
+import { readFile } from "./utils";
 import { convertToText } from "./conversion";
 
 export async function getHashes() {
-  const hashes = JSON.parse(await readFile(".knowhow/.hashes.json", "utf8"));
-  return hashes as Hashes;
+  try {
+    const hashes = JSON.parse(await readFile(".knowhow/.hashes.json", "utf8"));
+    return hashes as Hashes;
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      return {} as Hashes;
+    }
+    throw err;
+  }
 }
 
+/**
+ * Atomically save hashes to disk — writes to a temp file then renames,
+ * preventing concurrent writes from producing corrupted/truncated JSON.
+ */
 export async function saveHashes(hashes: any) {
-  await writeFile(".knowhow/.hashes.json", JSON.stringify(hashes, null, 2));
+  const target = ".knowhow/.hashes.json";
+  const tmp = `${target}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(hashes, null, 2));
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw err;
+  }
 }
 
 export async function md5Hash(str: string) {
@@ -35,18 +54,17 @@ export async function checkNoFilesChanged(
       return false;
     }
 
-    if (
+    // Check if this file has changed (either format)
+    const matchesLegacy =
       hashes[file].promptHash === promptHash &&
-      hashes[file].fileHash === fileHash
-    ) {
-      return true;
-    }
+      hashes[file].fileHash === fileHash;
+    const matchesCurrent = hashes[file][promptHash] === fileHash;
 
-    if (hashes[file][promptHash] === fileHash) {
-      return true;
+    if (!matchesLegacy && !matchesCurrent) {
+      // This file has changed — re-generation needed
+      return false;
     }
-
-    return false;
+    // This file is unchanged — continue checking the rest
   }
 
   return true;
@@ -90,17 +108,19 @@ export async function hasFileChangedSinceUpload(
 }
 
 /**
- * Saves the hash of the file at the time of a successful upload
+ * Mutates the provided hashes object with the upload hash for localPath.
+ * If no hashes object is provided, loads, mutates, and saves independently.
  */
-export async function saveUploadHash(localPath: string) {
-  const hashes = await getHashes();
+export async function saveUploadHash(localPath: string, hashes?: any) {
+  const standalone = !hashes;
+  if (standalone) hashes = await getHashes();
   const content = fs.readFileSync(localPath);
   const currentHash = crypto.createHash("md5").update(content).digest("hex");
   if (!hashes[localPath]) {
     hashes[localPath] = { fileHash: currentHash, promptHash: "" };
   }
   hashes[localPath][UPLOAD_KEY] = currentHash;
-  await saveHashes(hashes);
+  if (standalone) await saveHashes(hashes);
 }
 
 /**
@@ -120,18 +140,19 @@ export async function isLocalFileMatchingDownloadHash(
 }
 
 /**
- * Saves the SHA-256 hash of the file after a successful download so we can
- * skip unchanged files on the next sync.
+ * Mutates the provided hashes object with the download hash for localPath.
+ * If no hashes object is provided, loads, mutates, and saves independently.
  */
-export async function saveDownloadHash(localPath: string) {
-  const hashes = await getHashes();
+export async function saveDownloadHash(localPath: string, hashes?: any) {
+  const standalone = !hashes;
+  if (standalone) hashes = await getHashes();
   const content = fs.readFileSync(localPath);
   const currentHash = crypto.createHash("sha256").update(content).digest("base64");
   if (!hashes[localPath]) {
     hashes[localPath] = { fileHash: currentHash, promptHash: "" };
   }
   hashes[localPath][DOWNLOAD_KEY] = currentHash;
-  await saveHashes(hashes);
+  if (standalone) await saveHashes(hashes);
 }
 
 /**

package/src/index.ts

@@ -184,13 +184,15 @@ export async function upload() {
  *   - Standard glob patterns (e.g. "src/**\/*.ts")
  *   - Brace expansion (e.g. "{src/a.ts,src/b.ts}")
  *   - Comma-separated file paths (e.g. "src/a.ts,src/b.ts") — auto-converted to brace expansion
+ *   - Mixed comma-separated list with globs (e.g. "src/a.ts,src/commands/**\/*.ts")
  */
 function normalizeInputPattern(input: string): string {
-  // If it already has braces or glob chars other than comma, use as-is
-  if (input.includes("{") || input.includes("*") || input.includes("?")) {
+  // If it already has braces, use as-is (already brace-expanded)
+  if (input.includes("{")) {
     return input;
   }
   // If it contains commas, treat as comma-separated list and wrap in braces
+  // This also handles the mixed case: "src/a.ts,src/commands/**/*.ts"
   if (input.includes(",")) {
     const parts = input.split(",").map((p) => p.trim());
     return `{${parts.join(",")}}`;

package/src/processors/Base64ImageDetector.ts

@@ -17,6 +17,15 @@ interface TextContent {
   text: string;
 }
 
+/**
+ * Regex that matches common image file paths (absolute, relative, or just filenames)
+ * ending in a known image extension.
+ */
+const IMAGE_PATH_REGEX =
+  /(?:^|[\s"'(,\[{])([^\s"'(,\[{]*?\.(?:png|jpe?g|gif|webp|bmp|svg))(?=$|[\s"'),\]}])/gi;
+
+const IMAGE_EXTENSIONS = ["png", "jpeg", "jpg", "gif", "webp", "bmp", "svg"];
+
 export class Base64ImageProcessor {
   private imageDetail: "auto" | "low" | "high" = "auto";
   private supportedFormats = ["png", "jpeg", "jpg", "gif", "webp"];
@@ -118,6 +127,61 @@ export class Base64ImageProcessor {
     }
   }
 
+  /**
+   * Finds all image file paths mentioned in a text string.
+   * Returns deduplicated list of paths like "/tmp/screenshot.png" or "screenshot.jpg".
+   */
+  private findImageFilePaths(text: string): string[] {
+    const found: string[] = [];
+    const seen = new Set<string>();
+    IMAGE_PATH_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = IMAGE_PATH_REGEX.exec(text)) !== null) {
+      const filePath = match[1];
+      if (filePath && !seen.has(filePath)) {
+        seen.add(filePath);
+        found.push(filePath);
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Appends a hint to a text string if image file paths are detected.
+   * The hint tells the model it can use loadImageAsBase64 to view the image.
+   */
+  private addImagePathHint(text: string): string {
+    const paths = this.findImageFilePaths(text);
+    if (paths.length === 0) return text;
+
+    const hints = paths.map(
+      (p) =>
+        `loadImageAsBase64("${p}") to view the image at ${p}`
+    );
+
+    const hintBlock =
+      paths.length === 1
+        ? `\n\n[TIP: An image file path was detected: ${paths[0]}. Use the \`loadImageAsBase64\` tool with this path to load and view the image: ${hints[0]}]`
+        : `\n\n[TIP: Image file paths were detected. Use the \`loadImageAsBase64\` tool to load and view them:\n${hints.map((h) => `  - ${h}`).join("\n")}]`;
+
+    return text + hintBlock;
+  }
+
+  /**
+   * Applies image path hints to a message's text content items.
+   */
+  private applyImagePathHintsToMessage(message: Message): void {
+    if (typeof message.content === "string") {
+      message.content = this.addImagePathHint(message.content);
+    } else if (Array.isArray(message.content)) {
+      for (const item of message.content) {
+        if (item && (item as TextContent).type === "text" && typeof (item as TextContent).text === "string") {
+          (item as TextContent).text = this.addImagePathHint((item as TextContent).text);
+        }
+      }
+    }
+  }
+
   private processToolCallArguments(message: Message): void {
     if (message.tool_calls) {
       for (const toolCall of message.tool_calls) {
@@ -209,6 +273,15 @@ export class Base64ImageProcessor {
         // and converted to proper image content before the agent sees them
         if (message.role === "tool") {
           this.processToolMessageContent(message);
+          // After processing tool content (which may not convert to image if it's plain text
+          // describing a screenshot path), add hints for any image file paths found in the text.
+          this.applyImagePathHintsToMessage(message);
+        }
+
+        // Also apply hints to assistant messages — e.g. when an assistant message
+        // contains the result of a screenshot tool that returned a file path.
+        if (message.role === "assistant") {
+          this.applyImagePathHintsToMessage(message);
         }
 
         // Process tool calls in any message

package/src/services/MediaProcessorService.ts

@@ -1,9 +1,10 @@
 import * as fs from "fs";
 import * as path from "path";
-import { exec } from "child_process";
+import { exec, spawn } from "child_process";
 import { promisify } from "util";
 import { fileExists, readFile, mkdir } from "../utils";
 import { AIClient } from "../clients";
+import { Models } from "../types";
 
 const execPromise = promisify(exec);
 
@@ -36,7 +37,7 @@ export interface KeyframeInfo {
  * audio/video processing steps after downloading with ytdl.
  */
 export class MediaProcessorService {
-  constructor(private clients: any) {}
+  constructor(private clients: AIClient) {}
 
   /**
    * Split an audio/video file into fixed-length mp3 chunks using ffmpeg.
@@ -45,7 +46,8 @@ export class MediaProcessorService {
     filePath: string,
     outputDir: string,
     CHUNK_LENGTH_SECONDS = 30,
-    reuseExistingChunks = true
+    reuseExistingChunks = true,
+    onProgress?: (progressFraction: number) => void
   ): Promise<string[]> {
     const parsed = path.parse(filePath);
     const fileName = parsed.name;
@@ -72,8 +74,70 @@ export class MediaProcessorService {
       }
     }
 
-    const command = `ffmpeg -i "${filePath}" -f segment -segment_time ${CHUNK_LENGTH_SECONDS} -map 0:a:0 -acodec mp3 -vn "${outputDirPath}/chunk%04d.mp3"`;
-    await execAsync(command);
+    // Use faster encoding settings:
+    // - mono audio (-ac 1): halves encoding work, Whisper handles mono fine
+    // - low bitrate (-b:a 32k): sufficient for speech, much faster encode + smaller files
+    // - fast preset not available for mp3 encoder, but limiting bitrate helps
+    // - -threads 0: use all available CPU threads for faster processing
+    // If the input is already an mp3, copy the audio stream to avoid re-encoding
+    const inputExt = path.extname(filePath).toLowerCase().replace('.', '');
+    const isAlreadyMp3 = inputExt === 'mp3';
+    const audioCodecArgs = isAlreadyMp3
+      ? '-acodec copy'
+      : '-acodec libmp3lame -ac 1 -b:a 32k -threads 0';
+
+    // Use -progress pipe:1 to get real-time progress from ffmpeg
+    // We need the total duration first to calculate fraction
+    await new Promise<void>((resolve, reject) => {
+      // Get total duration via ffprobe first
+      let totalDurationSeconds = 0;
+      exec(
+        `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${filePath}"`,
+        (err, stdout) => {
+          if (!err && stdout.trim()) {
+            totalDurationSeconds = parseFloat(stdout.trim()) || 0;
+          }
+
+          // Now run ffmpeg with progress reporting
+          const args = [
+            '-i', filePath,
+            '-f', 'segment',
+            '-segment_time', String(CHUNK_LENGTH_SECONDS),
+            '-map', '0:a:0',
+            ...audioCodecArgs.split(' '),
+            '-vn',
+            ...(onProgress ? ['-progress', 'pipe:1'] : []),
+            `${outputDirPath}/chunk%04d.mp3`,
+          ];
+
+          const proc = spawn('ffmpeg', args);
+
+          let stdoutBuf = '';
+          proc.stdout?.on('data', (data: Buffer) => {
+            stdoutBuf += data.toString();
+            if (onProgress && totalDurationSeconds > 0) {
+              // ffmpeg -progress outputs key=value lines; look for out_time_ms
+              const match = stdoutBuf.match(/out_time_ms=(\d+)/g);
+              if (match) {
+                const last = match[match.length - 1];
+                const ms = parseInt(last.split('=')[1], 10);
+                const fraction = Math.min(ms / 1000 / totalDurationSeconds, 1);
+                onProgress(fraction);
+                // Keep only tail to avoid unbounded buffer growth
+                stdoutBuf = stdoutBuf.slice(-500);
+              }
+            }
+          });
+
+          proc.on('close', (code) => {
+            if (code === 0) resolve();
+            else reject(new Error(`ffmpeg exited with code ${code}`));
+          });
+          proc.on('error', reject);
+        }
+      );
+    });
+
     await fs.promises.writeFile(doneFilePath, "done");
 
     const folderFiles = await fs.promises.readdir(outputDirPath);
@@ -298,8 +362,9 @@ export class MediaProcessorService {
     });
     const image = `data:image/jpeg;base64,${base64}`;
     return this.clients.createCompletion("openai", {
-      model: "gpt-4o",
+      model: Models.openai.GPT_4o,
       max_tokens: 2500,
+      timeout: 20000,
       messages: [
         {
           role: "user",
@@ -315,7 +380,8 @@ export class MediaProcessorService {
   async *streamProcessVideo(
     filePath: string,
     reusePreviousTranscript = true,
-    chunkTime = 30
+    chunkTime = 30,
+    onChunkingProgress?: (fraction: number) => void
   ) {
     const parsed = path.parse(filePath);
     const videoJson = `${parsed.dir}/${parsed.name}/video.json`;
@@ -324,7 +390,8 @@ export class MediaProcessorService {
     const transcriptions = this.streamProcessAudio(
       filePath,
       reusePreviousTranscript,
-      chunkTime
+      chunkTime,
+      onChunkingProgress
     );
 
     console.log("Extracting keyframes...");
@@ -352,7 +419,8 @@ export class MediaProcessorService {
   async *streamProcessAudio(
     filePath: string,
     reusePreviousTranscript = true,
-    chunkTime = 30
+    chunkTime = 30,
+    onChunkingProgress?: (fraction: number) => void
   ): AsyncGenerator<TranscriptChunk> {
     const parsed = path.parse(filePath);
     const outputPath = `${parsed.dir}/${parsed.name}/transcript.json`;
@@ -382,7 +450,8 @@ export class MediaProcessorService {
       filePath,
       parsed.dir,
       chunkTime,
-      reusePreviousTranscript
+      reusePreviousTranscript,
+      onChunkingProgress
     );
 
     for await (const chunk of this.streamTranscription(

package/src/services/modules/index.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import * as os from "os";
 
 import { getConfig, getGlobalConfig } from "../../config";
 import { KnowhowModule, ModuleContext } from "./types";
@@ -26,29 +27,57 @@ export class ModulesService {
 
     const allModulePaths = config.modules;
 
+    // Search paths: .knowhow/node_modules first (where `knowhow modules install`
+    // puts packages), then cwd node_modules, then global node_modules.
+    // This allows modules installed via `knowhow modules install` to be found
+    // even when knowhow itself is installed globally.
+    const resolvePaths = [
+      path.join(process.cwd(), ".knowhow", "node_modules"),
+      path.join(os.homedir(), ".knowhow", "node_modules"),
+      path.join(process.cwd(), "node_modules"),
+    ];
+
     for (const modulePath of allModulePaths) {
       // Resolve relative paths relative to process.cwd() so that paths like
       // "../../packages/knowhow-module-load-webpage" in knowhow.json work
       // regardless of where the compiled output lives.
-      const resolvedPath = modulePath.startsWith(".")
-        ? path.resolve(process.cwd(), modulePath)
-        : modulePath;
-      const rawModule = require(resolvedPath);
-      const importedModule = (rawModule.default || rawModule) as KnowhowModule;
-      context.Events?.log(
-        "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})`
-      );
+      let resolvedPath: string;
+      if (modulePath.startsWith(".")) {
+        resolvedPath = path.resolve(process.cwd(), modulePath);
+      } else {
+        // For npm package names, try resolving from cwd first so locally-installed
+        // modules are found even when knowhow is installed globally.
+        try {
+          resolvedPath = require.resolve(modulePath, { paths: resolvePaths });
+        } catch {
+          resolvedPath = modulePath; // fall back to normal require resolution
+        }
+      }
 
+      let importedModule: KnowhowModule;
+      try {
+        const rawModule = require(resolvedPath);
+        importedModule = (rawModule.default || rawModule) as KnowhowModule;
+        context.Events?.log(
+          "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})`
+        );
+      } catch (err: any) {
+        process.stderr.write(
+          `\n⚠️  Failed to load module "${modulePath}": ${err.message}\n` +
+          `   Run "knowhow modules setup --global" or "knowhow modules install ${modulePath} --global" to fix this.\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) {