@tyvm/knowhow 0.0.103 → 0.0.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.103",
+  "version": "0.0.105",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/clients/index.ts

@@ -30,6 +30,32 @@ import { ModelProvider } from "../types";
 import { getConfig } from "../config";
 import { loadKnowhowJwt, KNOWHOW_API_URL } from "../services/KnowhowClient";
 import { ContextLimits } from "./contextLimits";
+import { OpenAiTextPricing } from "./pricing/openai";
+import { AnthropicTextPricing } from "./pricing/anthropic";
+import { GeminiPricing } from "./pricing/google";
+import {
+  XaiTextPricing,
+  XaiImagePricing,
+  XaiVideoPricing,
+} from "./pricing/xai";
+import type {
+  ModelPricing,
+  ModelType,
+  ModelCatalogEntry,
+} from "./pricing/types";
+export {
+  OpenAiTextPricing,
+  AnthropicTextPricing,
+  GeminiPricing,
+  XaiTextPricing,
+  XaiImagePricing,
+  XaiVideoPricing,
+};
+export type {
+  ModelPricing,
+  ModelType,
+  ModelCatalogEntry,
+} from "./pricing/types";
 
 // ---------------------------------------------------------------------------
 // Built-in provider registry
@@ -219,7 +245,9 @@ export class AIClient {
 
       if (!client) {
         if (entry.provider === "knowhow") {
-          console.warn(`⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`);
+          console.warn(
+            `⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`
+          );
         }
         continue;
       }
@@ -499,17 +527,22 @@ export class AIClient {
     }
 
     const allModels = this.listAllModels();
-    const hasKnowhowModels =
-      allModels["knowhow"] && allModels["knowhow"].length > 0;
+    const hasKnowhowModels = allModels.knowhow && allModels.knowhow.length > 0;
     const knowhowIsConfigured = Object.keys(allModels).includes("knowhow");
 
-    console.warn(`⚠️  Unable to find model '${model}' for provider '${provider}'.`);
-    console.warn(`   Available providers: ${Object.keys(allModels).join(", ") || "(none)"}`);
+    console.warn(
+      `⚠️  Unable to find model '${model}' for provider '${provider}'.`
+    );
+    console.warn(
+      `   Available providers: ${Object.keys(allModels).join(", ") || "(none)"}`
+    );
 
     if (!hasKnowhowModels && !knowhowIsConfigured) {
       console.warn(`   Tip: Run 'knowhow login' to enable Knowhow models.`);
     } else if (!hasKnowhowModels) {
-      console.warn(`   Tip: The Knowhow provider returned no models. Try running 'knowhow login' to re-authenticate.`);
+      console.warn(
+        `   Tip: The Knowhow provider returned no models. Try running 'knowhow login' to re-authenticate.`
+      );
     }
 
     return { provider, model };
@@ -763,6 +796,67 @@ export class AIClient {
     if (contextLimit === undefined) return undefined;
     return { contextLimit, threshold: contextLimit };
   }
+
+  /**
+   * Returns pricing information for all known models, derived from the
+   * provider pricing maps.
+   *
+   * @param modelId  Optional model id filter (without provider prefix).
+   *                 If omitted, all models across all providers are returned.
+   */
+  getPrices(modelId?: string): ModelCatalogEntry[] {
+    const results: ModelCatalogEntry[] = [];
+
+    const addModels = (
+      models: Record<string, string[]>,
+      type: ModelType,
+      pricingMap: Record<string, ModelPricing>
+    ) => {
+      for (const [provider, ids] of Object.entries(models)) {
+        for (const id of ids) {
+          if (modelId && id !== modelId) continue;
+          if (!pricingMap[id]) continue;
+
+          const p = pricingMap[id];
+          results.push({
+            id,
+            provider,
+            type,
+            displayName: id,
+            pricing: p,
+          });
+        }
+      }
+    };
+
+    // Build a combined pricing map across all providers
+    const allTextPricing: Record<string, ModelPricing> = {
+      ...OpenAiTextPricing,
+      ...AnthropicTextPricing,
+      ...GeminiPricing,
+      ...XaiTextPricing,
+    };
+    const allImagePricing: Record<string, ModelPricing> = {
+      ...XaiImagePricing,
+    };
+    const allVideoPricing: Record<string, ModelPricing> = {
+      ...XaiVideoPricing,
+    };
+
+    addModels(this.completionModels, "completion", allTextPricing);
+    addModels(this.embeddingModels, "embedding", allTextPricing);
+    addModels(this.imageModels, "image", {
+      ...allTextPricing,
+      ...allImagePricing,
+    });
+    addModels(this.audioModels, "audio", allTextPricing);
+    addModels(this.videoModels, "video", {
+      ...allTextPricing,
+      ...allVideoPricing,
+    });
+
+    return results;
+  }
 }
 
 export const Clients = new AIClient();

package/src/clients/pricing/index.ts

@@ -2,3 +2,5 @@ export { OpenAiTextPricing } from "./openai";
 export { GeminiTextPricing } from "./google";
 export { AnthropicTextPricing } from "./anthropic";
 export { XaiTextPricing, XaiImagePricing, XaiVideoPricing } from "./xai";
+export { ALL_MODEL_CATALOG, OPENAI_MODEL_CATALOG, ANTHROPIC_MODEL_CATALOG, GOOGLE_MODEL_CATALOG, XAI_MODEL_CATALOG, USAGE_MARKUP_PERCENT } from "./models";
+export type { ModelCatalogEntry, ModelType, ModelPricing as CatalogModelPricing } from "./types";

package/src/clients/pricing/models.ts

@@ -0,0 +1,252 @@
+/**
+ * Model catalog: a single source of truth for all supported AI models,
+ * their providers, types, display names, and pricing.
+ *
+ * Pricing is in USD per 1M tokens (or per-image / per-second for media models).
+ * This is exported so the Knowhow backend (and other consumers) can import
+ * model/pricing data without duplicating it.
+ */
+
+import { Models, EmbeddingModels } from "../../types";
+import { OpenAiTextPricing } from "./openai";
+import { AnthropicTextPricing } from "./anthropic";
+import { GeminiPricing } from "./google";
+import { XaiTextPricing, XaiImagePricing, XaiVideoPricing } from "./xai";
+import { ModelPricing, ModelType, ModelCatalogEntry } from "./types";
+
+export { ModelPricing, ModelType, ModelCatalogEntry };
+
+// ─── Platform markup ──────────────────────────────────────────────────────────
+
+/** 2.5% platform markup applied on top of all provider base rates */
+export const USAGE_MARKUP_PERCENT = 2.5 / 100;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function completion(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricingOverride?: Partial<ModelPricing>
+): ModelCatalogEntry {
+  const base =
+    (OpenAiTextPricing as Record<string, Partial<ModelPricing>>)[id] ||
+    (AnthropicTextPricing as Record<string, Partial<ModelPricing>>)[id] ||
+    (GeminiPricing as Record<string, Partial<ModelPricing>>)[id] ||
+    (XaiTextPricing as Record<string, Partial<ModelPricing>>)[id] ||
+    {};
+  return {
+    id,
+    provider,
+    type: "completion",
+    displayName,
+    pricing: {
+      input: 0,
+      output: 0,
+      ...base,
+      ...pricingOverride,
+    },
+  };
+}
+
+function embedding(
+  id: string,
+  provider: string,
+  displayName: string,
+  input: number
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "embedding",
+    displayName,
+    pricing: { input, output: 0 },
+  };
+}
+
+function image(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricing: Partial<ModelPricing>
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "image",
+    displayName,
+    pricing: { input: 0, output: 0, ...pricing },
+  };
+}
+
+function video(
+  id: string,
+  provider: string,
+  displayName: string,
+  video_generation: number
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "video",
+    displayName,
+    pricing: { input: 0, output: 0, video_generation },
+  };
+}
+
+function audio(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricing: Partial<ModelPricing>
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "audio",
+    displayName,
+    pricing: { input: 0, output: 0, ...pricing },
+  };
+}
+
+function transaction(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricing: Partial<ModelPricing>
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "transaction",
+    displayName,
+    pricing: { input: 0, output: 0, ...pricing },
+  };
+}
+
+// ─── OpenAI ───────────────────────────────────────────────────────────────────
+
+export const OPENAI_MODEL_CATALOG: ModelCatalogEntry[] = [
+  // Completion
+  completion(Models.openai.GPT_4o, "openai", "GPT-4o"),
+  completion(Models.openai.GPT_4o_Mini, "openai", "GPT-4o Mini"),
+  completion(Models.openai.GPT_41, "openai", "GPT-4.1"),
+  completion(Models.openai.GPT_41_Mini, "openai", "GPT-4.1 Mini"),
+  completion(Models.openai.GPT_41_Nano, "openai", "GPT-4.1 Nano"),
+  completion(Models.openai.GPT_45, "openai", "GPT-4.5 Preview"),
+  completion(Models.openai.o1, "openai", "o1"),
+  completion(Models.openai.o1_Mini, "openai", "o1 Mini"),
+  completion(Models.openai.o3, "openai", "o3"),
+  completion(Models.openai.o3_Mini, "openai", "o3 Mini"),
+  completion(Models.openai.o4_Mini, "openai", "o4 Mini"),
+  // Embedding
+  embedding(EmbeddingModels.openai.EmbeddingAda2, "openai", "Embedding Ada 002", OpenAiTextPricing[EmbeddingModels.openai.EmbeddingAda2]?.input ?? 0.1),
+  embedding(EmbeddingModels.openai.EmbeddingLarge3, "openai", "Embedding 3 Large", OpenAiTextPricing[EmbeddingModels.openai.EmbeddingLarge3]?.input ?? 0.13),
+  embedding(EmbeddingModels.openai.EmbeddingSmall3, "openai", "Embedding 3 Small", OpenAiTextPricing[EmbeddingModels.openai.EmbeddingSmall3]?.input ?? 0.02),
+  // Image generation
+  image(Models.openai.DALL_E_3, "openai", "DALL-E 3", { image_generation: 0.04 }),
+  image(Models.openai.DALL_E_2, "openai", "DALL-E 2", { image_generation: 0.02 }),
+  image(Models.openai.GPT_Image_15, "openai", "GPT Image 1.5", { input: OpenAiTextPricing[Models.openai.GPT_Image_15]?.input ?? 5.0, output: OpenAiTextPricing[Models.openai.GPT_Image_15]?.output ?? 10.0 }),
+  image(Models.openai.GPT_Image_1_Mini, "openai", "GPT Image 1 Mini", { input: OpenAiTextPricing[Models.openai.GPT_Image_1_Mini]?.input ?? 2.0 }),
+  // Video generation
+  video(Models.openai.Sora, "openai", "Sora", 0.012),
+  video(Models.openai.Sora_2, "openai", "Sora 2", 0.015),
+  // Audio
+  audio(Models.openai.TTS_1, "openai", "TTS-1", { input: 15.0 }),
+  audio(Models.openai.Whisper_1, "openai", "Whisper 1", { input: 0.006 }),
+  // Transaction / Search
+  transaction(Models.openai.GPT_4o_Mini_Search, "openai", "GPT-4o Mini Search", { input: OpenAiTextPricing[Models.openai.GPT_4o_Mini_Search]?.input ?? 0.15, output: OpenAiTextPricing[Models.openai.GPT_4o_Mini_Search]?.output ?? 0.6 }),
+  transaction(Models.openai.GPT_4o_Search, "openai", "GPT-4o Search", { input: OpenAiTextPricing[Models.openai.GPT_4o_Search]?.input ?? 2.5, output: OpenAiTextPricing[Models.openai.GPT_4o_Search]?.output ?? 10.0 }),
+];
+
+// ─── Anthropic ────────────────────────────────────────────────────────────────
+
+export const ANTHROPIC_MODEL_CATALOG: ModelCatalogEntry[] = [
+  completion(Models.anthropic.Opus4_5, "anthropic", "Claude Opus 4.5"),
+  completion(Models.anthropic.Sonnet4_5, "anthropic", "Claude Sonnet 4.5"),
+  completion(Models.anthropic.Opus4, "anthropic", "Claude Opus 4"),
+  completion(Models.anthropic.Sonnet4, "anthropic", "Claude Sonnet 4"),
+  completion(Models.anthropic.Haiku4_5, "anthropic", "Claude Haiku 4.5"),
+  completion(Models.anthropic.Sonnet3_7, "anthropic", "Claude Sonnet 3.7"),
+  completion(Models.anthropic.Sonnet3_5, "anthropic", "Claude Sonnet 3.5"),
+  completion(Models.anthropic.Haiku3, "anthropic", "Claude Haiku 3"),
+  completion(Models.anthropic.Opus3, "anthropic", "Claude Opus 3"),
+];
+
+// ─── Google ───────────────────────────────────────────────────────────────────
+
+export const GOOGLE_MODEL_CATALOG: ModelCatalogEntry[] = [
+  // Completion
+  completion(Models.google.Gemini_25_Pro, "google", "Gemini 2.5 Pro"),
+  completion(Models.google.Gemini_25_Flash, "google", "Gemini 2.5 Flash"),
+  completion(Models.google.Gemini_25_Flash_Lite, "google", "Gemini 2.5 Flash Lite"),
+  completion(Models.google.Gemini_20_Flash, "google", "Gemini 2.0 Flash"),
+  completion(Models.google.Gemini_15_Pro, "google", "Gemini 1.5 Pro"),
+  completion(Models.google.Gemini_15_Flash, "google", "Gemini 1.5 Flash"),
+  completion(Models.google.Gemini_15_Flash_8B, "google", "Gemini 1.5 Flash 8B"),
+  // Embedding
+  embedding(EmbeddingModels.google.Gemini_Embedding, "google", "Gemini Embedding", GeminiPricing[EmbeddingModels.google.Gemini_Embedding]?.input ?? 0),
+  // Image generation
+  image(Models.google.Gemini_20_Flash_Preview_Image_Generation, "google", "Gemini 2.0 Flash Image", {
+    input: GeminiPricing[Models.google.Gemini_20_Flash_Preview_Image_Generation]?.input ?? 0.1,
+    output: GeminiPricing[Models.google.Gemini_20_Flash_Preview_Image_Generation]?.output ?? 0.4,
+    image_generation: GeminiPricing[Models.google.Gemini_20_Flash_Preview_Image_Generation]?.image_generation ?? 0.039,
+  }),
+  image(Models.google.Gemini_25_Flash_Image, "google", "Gemini 2.5 Flash Image", {
+    input: GeminiPricing[Models.google.Gemini_25_Flash_Image]?.input ?? 0.3,
+    output: GeminiPricing[Models.google.Gemini_25_Flash_Image]?.output ?? 0.039,
+    image_generation: GeminiPricing[Models.google.Gemini_25_Flash_Image]?.image_generation ?? 0.039,
+  }),
+  image(Models.google.Gemini_31_Flash_Image_Preview, "google", "Gemini 3.1 Flash Image", {
+    input: GeminiPricing[Models.google.Gemini_31_Flash_Image_Preview]?.input ?? 0.5,
+    output: GeminiPricing[Models.google.Gemini_31_Flash_Image_Preview]?.output ?? 3.0,
+    image_generation: GeminiPricing[Models.google.Gemini_31_Flash_Image_Preview]?.image_generation ?? 0.045,
+  }),
+  image(Models.google.Gemini_3_Pro_Image_Preview, "google", "Gemini 3 Pro Image", {
+    input: GeminiPricing[Models.google.Gemini_3_Pro_Image_Preview]?.input ?? 2.0,
+    output: GeminiPricing[Models.google.Gemini_3_Pro_Image_Preview]?.output ?? 12.0,
+    image_generation: GeminiPricing[Models.google.Gemini_3_Pro_Image_Preview]?.image_generation ?? 0.134,
+  }),
+  image(Models.google.Imagen_3, "google", "Imagen 4", { image_generation: GeminiPricing[Models.google.Imagen_3]?.image_generation ?? 0.04 }),
+  image(Models.google.Imagen_4_Fast, "google", "Imagen 4 Fast", { image_generation: GeminiPricing[Models.google.Imagen_4_Fast]?.image_generation ?? 0.02 }),
+  image(Models.google.Imagen_4_Ultra, "google", "Imagen 4 Ultra", { image_generation: GeminiPricing[Models.google.Imagen_4_Ultra]?.image_generation ?? 0.06 }),
+  // Video generation
+  video(Models.google.Veo_2, "google", "Veo 2", GeminiPricing[Models.google.Veo_2]?.video_generation ?? 0.35),
+  video(Models.google.Veo_3, "google", "Veo 3", GeminiPricing[Models.google.Veo_3]?.video_generation ?? 0.4),
+  video(Models.google.Veo_3_Fast, "google", "Veo 3 Fast", GeminiPricing[Models.google.Veo_3_Fast]?.video_generation ?? 0.1),
+  // Audio (TTS)
+  audio(Models.google.Gemini_25_Flash_TTS, "google", "Gemini 2.5 Flash TTS", {
+    input: GeminiPricing[Models.google.Gemini_25_Flash_TTS]?.input ?? 0.5,
+    output_audio: GeminiPricing[Models.google.Gemini_25_Flash_TTS]?.output_audio ?? 10.0,
+    output: GeminiPricing[Models.google.Gemini_25_Flash_TTS]?.output_audio ?? 10.0,
+  }),
+  audio(Models.google.Gemini_25_Pro_TTS, "google", "Gemini 2.5 Pro TTS", {
+    input: GeminiPricing[Models.google.Gemini_25_Pro_TTS]?.input ?? 1.0,
+    output_audio: GeminiPricing[Models.google.Gemini_25_Pro_TTS]?.output_audio ?? 20.0,
+    output: GeminiPricing[Models.google.Gemini_25_Pro_TTS]?.output_audio ?? 20.0,
+  }),
+];
+
+// ─── xAI ──────────────────────────────────────────────────────────────────────
+
+export const XAI_MODEL_CATALOG: ModelCatalogEntry[] = [
+  completion(Models.xai.Grok4, "xai", "Grok 4"),
+  completion(Models.xai.Grok3Beta, "xai", "Grok 3 Beta"),
+  completion(Models.xai.Grok3MiniBeta, "xai", "Grok 3 Mini Beta"),
+  completion(Models.xai.Grok3FastBeta, "xai", "Grok 3 Fast Beta"),
+  completion(Models.xai.Grok21212, "xai", "Grok 2"),
+  // Image generation
+  image(Models.xai.GrokImagineImage, "xai", "Grok Imagine Image", { image_generation: XaiImagePricing["grok-imagine-image"]?.image_generation ?? 0.02 }),
+  image("grok-2-image-1212", "xai", "Grok 2 Image", { image_generation: XaiImagePricing["grok-2-image-1212"]?.image_generation ?? 0.07 }),
+  // Video generation
+  video(Models.xai.GrokImagineVideo, "xai", "Grok Imagine Video", XaiVideoPricing["grok-imagine-video"]?.video_generation ?? 0.05),
+];
+
+// ─── Combined catalog ─────────────────────────────────────────────────────────
+
+export const ALL_MODEL_CATALOG: ModelCatalogEntry[] = [
+  ...OPENAI_MODEL_CATALOG,
+  ...ANTHROPIC_MODEL_CATALOG,
+  ...GOOGLE_MODEL_CATALOG,
+  ...XAI_MODEL_CATALOG,
+];

package/src/clients/pricing/types.ts

@@ -0,0 +1,29 @@
+export type ModelType =
+  | "completion"
+  | "embedding"
+  | "image"
+  | "audio"
+  | "video"
+  | "transaction";
+
+export interface ModelPricing {
+  input?: number;
+  output?: number;
+  cached_input?: number;
+  cache_write?: number;
+  cache_hit?: number;
+  input_audio?: number;
+  output_audio?: number;
+  input_gt_200k?: number;
+  output_gt_200k?: number;
+  image_generation?: number;
+  video_generation?: number;
+}
+
+export interface ModelCatalogEntry {
+  id: string;
+  provider: string;
+  type: ModelType;
+  displayName: string;
+  pricing: ModelPricing;
+}

package/src/clients/pricing/xai.ts

@@ -1,4 +1,5 @@
 import { Models } from "../../types";
+import { ModelPricing } from "./types";
 
 export const XaiTextPricing = {
 
@@ -60,14 +61,14 @@ export const XaiTextPricing = {
 
 // Image generation pricing: per image
 // Based on https://docs.x.ai/developers/models
-export const XaiImagePricing = {
-  "grok-imagine-image-pro": 0.07,
-  "grok-imagine-image": 0.02,
-  "grok-2-image-1212": 0.07,
+export const XaiImagePricing: Record<string, ModelPricing> = {
+  "grok-imagine-image-pro": { image_generation: 0.07 },
+  "grok-imagine-image": { image_generation: 0.02 },
+  "grok-2-image-1212": { image_generation: 0.07 },
 };
 
 // Video generation pricing: $0.05 per second
 // Based on https://docs.x.ai/developers/models
-export const XaiVideoPricing = {
-  "grok-imagine-video": 0.05, // per second
+export const XaiVideoPricing: Record<string, ModelPricing> = {
+  "grok-imagine-video": { video_generation: 0.05 }, // per second
 };

package/src/clients/xai.ts

@@ -175,7 +175,7 @@ export class GenericXAIClient implements GenericClient {
     // Calculate cost based on model name
     const imageModel = options.model || "grok-imagine-image";
     const costPerImage =
-      XaiImagePricing[imageModel as keyof typeof XaiImagePricing] || 0.02;
+      XaiImagePricing[imageModel as keyof typeof XaiImagePricing]?.image_generation || 0.02;
     const usdCost = (options.n || 1) * costPerImage;
 
     return {
@@ -250,7 +250,7 @@ export class GenericXAIClient implements GenericClient {
     // Return immediately with the jobId – do NOT poll here.
     // Use getVideoStatus() to poll and downloadVideo() to fetch the result.
     const duration = options.duration || 5;
-    const pricePerSecond = XaiVideoPricing[model] || 0.07;
+    const pricePerSecond = XaiVideoPricing[model]?.video_generation || 0.07;
     const usdCost = duration * pricePerSecond;
 
     return {

package/src/fileSync.ts

@@ -5,7 +5,7 @@ import { loadJwt } from "./login";
 import { getConfig } from "./config";
 import { services } from "./services";
 import { S3Service } from "./services/S3";
-import { getHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote } from "./hashes";
+import { getHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote, isLocalFileMatchingDownloadHash, saveDownloadHash } from "./hashes";
 
 export interface FileSyncOptions {
   upload?: boolean;
@@ -145,12 +145,21 @@ async function downloadFile(
   }
 
   try {
+    // Fast-path: check stored download hash before hitting the API
+    const hashes = await getHashes();
+    if (await isLocalFileMatchingDownloadHash(localPath, hashes)) {
+      console.log(`   ✓ Skipping ${localPath} (matches stored download hash)`);
+      return;
+    }
+
     // Get presigned download URL + remote checksum
     const { downloadUrl, checksumSHA256 } = await client.getOrgFilePresignedDownloadUrl(remotePath);
 
     // Skip if local file matches remote checksum
     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);
       return;
     }
 
@@ -163,6 +172,9 @@ async function downloadFile(
     // Download file using presigned URL
     await s3Service.downloadFromPresignedUrl(downloadUrl, localPath);
 
+    // Save download hash so we can skip unchanged files next time
+    await saveDownloadHash(localPath);
+
     // Get file size for logging
     const stats = fs.statSync(localPath);
     console.log(`   ✓ Downloaded ${stats.size} bytes`);
@@ -284,7 +296,8 @@ async function downloadDirectory(
     const fullPath = f.folderPath.endsWith("/")
       ? f.folderPath + f.fileName
       : f.folderPath + "/" + f.fileName;
-    return fullPath.startsWith(remoteDir);
+    // Exclude directory placeholder entries (empty fileName) and only include real files
+    return f.fileName !== "" && fullPath.startsWith(remoteDir);
   });
 
   if (matchingFiles.length === 0) {

package/src/hashes.ts

@@ -73,6 +73,8 @@ export async function saveAllFileHashes(files: string[], promptHash: string) {
 
 const UPLOAD_KEY = "upload";
 
+const DOWNLOAD_KEY = "download";
+
 /**
  * Returns true if the file has changed since the last successful upload
  * (or if it has never been uploaded before)
@@ -101,6 +103,37 @@ export async function saveUploadHash(localPath: string) {
   await saveHashes(hashes);
 }
 
+/**
+ * Returns true if the local file already matches the hash stored from
+ * the last successful download, meaning we can skip the download.
+ */
+export async function isLocalFileMatchingDownloadHash(
+  localPath: string,
+  hashes: any
+): Promise<boolean> {
+  if (!fs.existsSync(localPath)) return false;
+  const storedHash = hashes[localPath]?.[DOWNLOAD_KEY];
+  if (!storedHash) return false;
+  const content = fs.readFileSync(localPath);
+  const currentHash = crypto.createHash("sha256").update(content).digest("base64");
+  return storedHash === currentHash;
+}
+
+/**
+ * Saves the SHA-256 hash of the file after a successful download so we can
+ * skip unchanged files on the next sync.
+ */
+export async function saveDownloadHash(localPath: string) {
+  const 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);
+}
+
 /**
  * Compute SHA-256 of a local file, returned as base64 (matches S3 encoding)
  */

package/src/services/AgentSyncFs.ts

@@ -18,13 +18,17 @@ export interface FsSyncOptions {
  * Creates files in .knowhow/processes/agents/{taskId}/ for status and input
  */
 export class AgentSyncFs {
+  /** Shared cleanup interval across all instances to avoid duplicate cleanup runs */
+  private static sharedCleanupInterval: NodeJS.Timeout | null = null;
+  private static sharedBasePath: string = ".knowhow/processes/agents";
+  private static cleanupStarted: boolean = false;
+
   private taskId: string | undefined;
   private basePath: string = ".knowhow/processes/agents";
   private taskPath: string | undefined;
   private eventHandlersSetup: boolean = false;
   private watcher: ReturnType<typeof watch> | null = null;
   private lastInputContent: string = "";
-  private cleanupInterval: NodeJS.Timeout | null = null;
   private finalizationPromise: Promise<void> | null = null;
   private agent: BaseAgent | undefined;
   private threadUpdateHandler: ((...args: any[]) => void) | undefined;
@@ -38,7 +42,7 @@ export class AgentSyncFs {
 
   constructor() {
     // Start cleanup process when created
-    this.startCleanupProcess();
+    AgentSyncFs.startSharedCleanupProcess();
   }
 
   /**
@@ -372,9 +376,9 @@ export class AgentSyncFs {
   /**
    * Clean up old task directories (older than 3 days)
    */
-  private async cleanupOldTasks(): Promise<void> {
+  private static async cleanupOldTasks(): Promise<void> {
     try {
-      const agentsPath = this.basePath;
+      const agentsPath = AgentSyncFs.sharedBasePath;
       
       // Check if directory exists
       try {
@@ -414,23 +418,27 @@ export class AgentSyncFs {
   /**
    * Start periodic cleanup process
    */
-  private startCleanupProcess(): void {
-    // Run cleanup every hour
-    this.cleanupInterval = setInterval(() => {
-      this.cleanupOldTasks();
+  private static startSharedCleanupProcess(): void {
+    if (AgentSyncFs.cleanupStarted) return;
+    AgentSyncFs.cleanupStarted = true;
+
+    // Run cleanup every hour (shared across all instances)
+    AgentSyncFs.sharedCleanupInterval = setInterval(() => {
+      AgentSyncFs.cleanupOldTasks();
     }, 60 * 60 * 1000);
 
     // Also run once on startup
-    this.cleanupOldTasks();
+    AgentSyncFs.cleanupOldTasks();
   }
 
   /**
    * Stop cleanup process
    */
   stopCleanup(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
+    if (AgentSyncFs.sharedCleanupInterval) {
+      clearInterval(AgentSyncFs.sharedCleanupInterval);
+      AgentSyncFs.sharedCleanupInterval = null;
+      AgentSyncFs.cleanupStarted = false;
     }
   }