@tyvm/knowhow 0.0.109-dev.05fe5a0 → 0.0.109-dev.86123ed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.109-dev.05fe5a0",
+  "version": "0.0.109-dev.86123ed",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/agents/tools/list.ts

@@ -156,8 +156,8 @@ export const includedTools = [
           },
           model: {
             type: "string",
-            description: "The model to use (default: 'gpt-4o')",
-            default: "gpt-4o",
+            description: "The model to use (default: 'gpt-5.4-nano')",
+            default: "gpt-5.4-nano",
           },
         },
         required: ["imageUrl", "question"],

package/src/chat/CliChatService.ts

@@ -38,7 +38,7 @@ export class CliChatService implements ChatService {
       searchMode: false,
       voiceMode: false,
       multilineMode: false,
-      currentModel: "gpt-4o",
+      currentModel: "gpt-5.4-nano",
       currentProvider: "openai",
       chatHistory: this.chatHistory,
       plugins,

package/src/chat/modules/SystemModule.ts

@@ -45,7 +45,7 @@ export class SystemModule extends BaseChatModule {
     const agent = context?.selectedAgent;
     const Clients = agent.clientService;
     const currentProvider = context?.currentProvider || "openai";
-    const currentModel = context?.currentModel || "gpt-4o";
+    const currentModel = context?.currentModel || "gpt-5.4-nano";
 
     const models = Clients.getRegisteredModels(currentProvider);
     console.log(models);
@@ -86,7 +86,7 @@ export class SystemModule extends BaseChatModule {
     const Clients = agent.clientService;
 
     const currentProvider = context?.currentProvider || "openai";
-    const currentModel = context?.currentModel || "gpt-4o";
+    const currentModel = context?.currentModel || "gpt-5.4-nano";
 
     const providers = Object.keys(Clients.clients);
     console.log(providers);

package/src/clients/anthropic.ts

@@ -376,7 +376,7 @@ export class GenericAnthropicClient implements GenericClient {
           tool_choice: { type: "auto" },
           tools,
         }),
-      });
+      }, { signal: options.signal });
 
       if (!response.content || !response.content.length) {
         console.log("no content in Anthropic response", response);

package/src/clients/index.ts

@@ -33,6 +33,7 @@ import { ContextLimits } from "./contextLimits";
 import { OpenAiTextPricing } from "./pricing/openai";
 import { AnthropicTextPricing } from "./pricing/anthropic";
 import { GeminiPricing } from "./pricing/google";
+import { withRetry } from "./withRetry";
 import {
   XaiTextPricing,
   XaiImagePricing,
@@ -665,7 +666,10 @@ export class AIClient {
         } model registered. Try using ${JSON.stringify(this.listAllModels())}`
       );
     }
-    return client.createChatCompletion({ ...options, model });
+    return withRetry(
+      (signal) => client.createChatCompletion({ ...options, model, signal }),
+      options
+    );
   }
 
   async createEmbedding(
@@ -680,7 +684,10 @@ export class AIClient {
         } model registered. Try using ${JSON.stringify(this.listAllModels())}`
       );
     }
-    return client.createEmbedding({ ...options, model });
+    return withRetry(
+      (signal) => client.createEmbedding({ ...options, model, signal }),
+      options
+    );
   }
 
   async createAudioTranscription(
@@ -693,7 +700,10 @@ export class AIClient {
         `Provider ${provider} does not support audio transcription.`
       );
     }
-    return client.createAudioTranscription(options);
+    return withRetry(
+      (signal) => client.createAudioTranscription({ ...options, signal }),
+      options
+    );
   }
 
   async createAudioGeneration(
@@ -711,7 +721,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createAudioGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createAudioGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async createImageGeneration(
@@ -729,7 +742,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createImageGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createImageGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async createVideoGeneration(
@@ -747,7 +763,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createVideoGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createVideoGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async getVideoStatus(

package/src/clients/openai.ts

@@ -63,6 +63,10 @@ export class GenericOpenAiClient implements GenericClient {
     });
   }
 
+  /**
+   * Execute a function with timeout, retries, and exponential backoff.
+   * Retriable errors: 5xx, timeout, ECONNRESET, ETIMEDOUT, rate limits (429).
+   */
   reasoningEffort(
     messages: CompletionOptions["messages"]
   ): "low" | "medium" | "high" {
@@ -155,12 +159,11 @@ export class GenericOpenAiClient implements GenericClient {
         max_completion_tokens: Math.max(options.max_tokens ?? 0, 16_000),
         reasoning_effort: this.resolveReasoningEffort(options),
       }),
-
       ...(options.tools && {
         tools: options.tools,
         tool_choice: "auto",
       }),
-    });
+    }, { signal: options.signal });
 
     const usdCost = this.calculateCost(options.model, response.usage);
 
@@ -453,7 +456,7 @@ export class GenericOpenAiClient implements GenericClient {
       prompt: options.prompt,
       response_format: options.response_format || "verbose_json",
       temperature: options.temperature,
-    });
+    }, { signal: options.signal });
 
     // Calculate cost: $0.006 per minute for Whisper
     const duration = typeof response === "object" && "duration" in response && typeof response.duration === "number"
@@ -489,7 +492,7 @@ export class GenericOpenAiClient implements GenericClient {
       voice: options.voice as any,
       response_format: options.response_format || "mp3",
       speed: options.speed,
-    });
+    }, { signal: options.signal });
 
     const buffer = Buffer.from(await response.arrayBuffer());
 
@@ -518,7 +521,7 @@ export class GenericOpenAiClient implements GenericClient {
       style: options.style,
       response_format: options.response_format,
       user: options.user,
-    });
+    }, { signal: options.signal });
 
     // Cost calculation varies by model and settings
     // DALL-E 3: $0.040-$0.120 per image depending on quality/size

package/src/clients/types.ts

@@ -57,7 +57,30 @@ export interface ToolCall {
   };
 }
 
-export interface CompletionOptions {
+export interface RetryOptions {
+  /**
+   * Request timeout in milliseconds per attempt. If the request does not complete
+   * within this time it is aborted and retried according to maxRetries.
+   */
+  timeout?: number;
+  /**
+   * Maximum number of retry attempts for retriable errors (5xx, timeout, ECONNRESET, 429).
+   * Default: 2. Set to 0 to disable retries.
+   */
+  maxRetries?: number;
+  /**
+   * Base backoff delay in milliseconds for exponential retry backoff.
+   * Default: 1000ms. Each retry waits backoffMs * 2^attempt ms.
+   */
+  backoffMs?: number;
+  /**
+   * Optional external AbortSignal. When the signal is aborted the current
+   * attempt is cancelled immediately and no further retries are made.
+   */
+  signal?: AbortSignal;
+}
+
+export interface CompletionOptions extends RetryOptions {
   model: string;
   messages: Message[];
   tools?: Tool[];
@@ -113,7 +136,7 @@ export interface CompletionResponse {
   usd_cost?: number;
 }
 
-export interface EmbeddingOptions {
+export interface EmbeddingOptions extends RetryOptions {
   input: string;
   model?: string;
 }
@@ -132,7 +155,7 @@ export interface EmbeddingResponse {
   usd_cost?: number;
 }
 
-export interface AudioTranscriptionOptions {
+export interface AudioTranscriptionOptions extends RetryOptions {
   file: Blob | File | any; // Support for Node.js ReadStream or web File/Blob
   model?: string;
   language?: string;
@@ -162,7 +185,7 @@ export interface AudioTranscriptionResponse {
   usd_cost?: number;
 }
 
-export interface AudioGenerationOptions {
+export interface AudioGenerationOptions extends RetryOptions {
   model: string;
   input: string;
   voice: string; // e.g. "alloy", "echo", "fable", "onyx", "nova", "shimmer" for OpenAI; "Kore", "Puck" etc. for Gemini
@@ -176,7 +199,7 @@ export interface AudioGenerationResponse {
   usd_cost?: number;
 }
 
-export interface ImageGenerationOptions {
+export interface ImageGenerationOptions extends RetryOptions {
   model: string;
   prompt: string;
   n?: number;
@@ -197,7 +220,7 @@ export interface ImageGenerationResponse {
   usd_cost?: number;
 }
 
-export interface VideoGenerationOptions {
+export interface VideoGenerationOptions extends RetryOptions {
   model: string;
   prompt: string;
   duration?: number; // seconds

package/src/clients/withRetry.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared retry/timeout helper for all AI clients.
+ *
+ * Executes `fn` with exponential backoff for retriable errors:
+ * - Rate limits (429)
+ * - Timeouts (AbortError, ETIMEDOUT, ECONNRESET)
+ * - Server errors (5xx)
+ *
+ * @param fn               Function to execute. Receives a combined AbortSignal
+ *                         that fires on per-attempt timeout OR external signal abort.
+ * @param opts             Any object with optional RetryOptions fields (timeout, maxRetries,
+ *                         backoffMs, signal). Extra fields are ignored — so you can pass the
+ *                         full options object from any AI method directly.
+ *                         - timeout: Per-attempt timeout in ms. No timeout if omitted.
+ *                         - maxRetries: Max retry attempts after first failure. Default: 2.
+ *                         - backoffMs: Base backoff delay in ms. Default: 1000.
+ *                         - signal: Optional external AbortSignal. When aborted, the current
+ *                         attempt is cancelled and no further retries are made.
+ */
+import type { RetryOptions } from "./types";
+
+export async function withRetry<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  opts: RetryOptions = {}
+): Promise<T> {
+  const maxRetries = opts.maxRetries ?? 2;
+  const backoffMs = opts.backoffMs ?? 1000;
+  const timeout = opts.timeout;
+  const externalSignal = opts.signal;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    // If the external signal is already aborted, bail out immediately.
+    if (externalSignal?.aborted) {
+      throw externalSignal.reason ?? new DOMException("Aborted", "AbortError");
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    // Combine per-attempt timeout with the external signal into one controller.
+    const controller = timeout || externalSignal ? new AbortController() : undefined;
+
+    if (controller) {
+      if (timeout) {
+        timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout);
+      }
+      // Forward external signal abort into our combined controller.
+      if (externalSignal) {
+        const onExternalAbort = () => controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        if (externalSignal.aborted) {
+          controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        } else {
+          externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+          // Clean up the listener after the attempt resolves/rejects.
+          controller.signal.addEventListener("abort", () =>
+            externalSignal.removeEventListener("abort", onExternalAbort), { once: true }
+          );
+        }
+      }
+    }
+
+    try {
+      const result = await fn(controller?.signal);
+      return result;
+    } catch (err: unknown) {
+      clearTimeout(timer);
+      // If the external signal was aborted, don't retry — propagate immediately.
+      if (externalSignal?.aborted) {
+        throw err;
+      }
+      const errStr = String(err);
+      const isRetriable =
+        errStr.includes('429') ||
+        errStr.includes('timeout') ||
+        errStr.includes('TimeoutError') ||
+        errStr.includes('ECONNRESET') ||
+        errStr.includes('ETIMEDOUT') ||
+        errStr.includes('AbortError') ||
+        /5\d\d/.test(errStr);
+      if (isRetriable && attempt < maxRetries) {
+        const delay = backoffMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        continue;
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  throw new Error('withRetry: exhausted retries');
+}

package/src/config.ts

@@ -74,7 +74,7 @@ const defaultConfig = {
       description:
         "You can define agents in the config. They will have access to all tools.",
       instructions: "Reply to the user saying 'Hello, world!'",
-      model: "gpt-4o-2024-08-06",
+      model: "gpt-5.4-nano",
       provider: "openai",
     },
   ],

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) {
@@ -90,17 +109,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 +141,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/services/MediaProcessorService.ts

@@ -4,6 +4,7 @@ import { exec } 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.
@@ -298,7 +299,7 @@ export class MediaProcessorService {
     });
     const image = `data:image/jpeg;base64,${base64}`;
     return this.clients.createCompletion("openai", {
-      model: "gpt-4o",
+      model: Models.openai.GPT_54_Nano,
       max_tokens: 2500,
       messages: [
         {