@tyvm/knowhow 0.0.102 → 0.0.104

package/src/clients/pricing/catalog.ts

@@ -0,0 +1,287 @@
+/**
+ * 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";
+
+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;
+  /** Markup applied on top of base pricing (as a fraction, e.g. 0.025 = 2.5%) */
+  markupPercent: number;
+}
+
+// ─── 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,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    pricing: {
+      input: 0,
+      output: 0,
+      ...base,
+      ...pricingOverride,
+    },
+  };
+}
+
+function embedding(
+  id: string,
+  provider: string,
+  displayName: string,
+  input: number
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "embedding",
+    displayName,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    pricing: { input, output: 0 },
+  };
+}
+
+function image(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricing: Partial<ModelPricing>
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "image",
+    displayName,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    pricing: { input: 0, output: 0, ...pricing },
+  };
+}
+
+function video(
+  id: string,
+  provider: string,
+  displayName: string,
+  video_generation: number
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "video",
+    displayName,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    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,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    pricing: { input: 0, output: 0, ...pricing },
+  };
+}
+
+function transaction(
+  id: string,
+  provider: string,
+  displayName: string,
+  pricing: Partial<ModelPricing>
+): ModelCatalogEntry {
+  return {
+    id,
+    provider,
+    type: "transaction",
+    displayName,
+    markupPercent: USAGE_MARKUP_PERCENT,
+    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"] ?? 0.02 }),
+  image("grok-2-image-1212", "xai", "Grok 2 Image", { image_generation: XaiImagePricing["grok-2-image-1212"] ?? 0.07 }),
+  // Video generation
+  video(Models.xai.GrokImagineVideo, "xai", "Grok Imagine Video", XaiVideoPricing["grok-imagine-video"] ?? 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/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 "./catalog";
+export type { ModelCatalogEntry, ModelType, ModelPricing as CatalogModelPricing } from "./catalog";

package/src/config.ts

@@ -109,6 +109,8 @@ const defaultConfig = {
       allowedPorts: [],
     },
   },
+
+  syncRemote: false,
 } as Config;
 
 const defaultLanguage = {

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,21 +18,31 @@ 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;
   private doneHandler: ((...args: any[]) => void) | undefined;
+  /**
+   * Tracks the most recent in-flight filesystem metadata update.
+   * The done handler awaits this before finalizing, preventing a race where
+   * the completion call writes before the last thread sync finishes.
+   */
+  private pendingThreadUpdatePromise: Promise<void> | null = null;
 
   constructor() {
     // Start cleanup process when created
-    this.startCleanupProcess();
+    AgentSyncFs.startSharedCleanupProcess();
   }
 
   /**
@@ -294,8 +304,12 @@ export class AgentSyncFs {
       if (!this.taskId) return;
 
       try {
-        await this.updateMetadata(agent, true);
-        await this.checkForChanges(agent);
+        // Track the pending update so the done handler can await it.
+        this.pendingThreadUpdatePromise = (async () => {
+          await this.updateMetadata(agent, true);
+          await this.checkForChanges(agent);
+        })();
+        await this.pendingThreadUpdatePromise;
       } catch (error) {
         console.error(`❌ Error during threadUpdate sync:`, error);
       }
@@ -314,6 +328,17 @@ export class AgentSyncFs {
       // Store finalization promise so callers can await it (same pattern as AgentSyncKnowhowWeb)
       this.finalizationPromise = (async () => {
         try {
+          // Flush any in-flight thread update before finalizing.
+          // This prevents the race where a pending "inProgress: true" metadata write
+          // overwrites the finalization write.
+          if (this.pendingThreadUpdatePromise) {
+            console.log(`⏳ [AgentSyncFs] Awaiting pending thread update before finalizing...`);
+            await this.pendingThreadUpdatePromise.catch(() => {
+              // Ignore errors in pending update — we still want to finalize
+            });
+            this.pendingThreadUpdatePromise = null;
+          }
+
           await this.updateMetadata(agent, false, result);
           console.log(`✅ Completed filesystem sync for task: ${this.taskId}`);
           await this.cleanup();
@@ -351,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 {
@@ -393,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;
     }
   }
 
@@ -435,5 +464,6 @@ export class AgentSyncFs {
     this.eventHandlersSetup = false;
     this.lastInputContent = "";
     this.finalizationPromise = null;
+    this.pendingThreadUpdatePromise = null;
   }
 }

package/src/services/AgentSyncKnowhowWeb.ts

@@ -36,6 +36,12 @@ export class AgentSyncKnowhowWeb {
   private agent: BaseAgent | undefined;
   private threadUpdateHandler: ((...args: any[]) => void) | undefined;
   private doneHandler: ((...args: any[]) => void) | undefined;
+  /**
+   * Tracks the most recent in-flight thread update API call.
+   * The done handler awaits this before sending the finalization call,
+   * preventing a race where the completion overwrites a later in-progress update.
+   */
+  private pendingThreadUpdatePromise: Promise<void> | null = null;
 
   constructor(baseUrl: string = KNOWHOW_API_URL) {
     this.baseUrl = baseUrl;
@@ -240,11 +246,15 @@ export class AgentSyncKnowhowWeb {
       }
 
       try {
-        // Update task with current state
-        await this.updateChatTask(this.knowhowTaskId, agent, true);
-
-        // Check for pending messages, pause, or kill status
-        await this.checkAndProcessPendingMessages(agent, this.knowhowTaskId);
+        // Track the pending thread update so the done handler can await it.
+        this.pendingThreadUpdatePromise = (async () => {
+          // Update task with current state
+          await this.updateChatTask(this.knowhowTaskId!, agent, true);
+
+          // Check for pending messages, pause, or kill status
+          await this.checkAndProcessPendingMessages(agent, this.knowhowTaskId!);
+        })();
+        await this.pendingThreadUpdatePromise;
       } catch (error) {
         console.error(`❌ Error during threadUpdate sync:`, error);
         // Continue execution even if synchronization fails
@@ -264,6 +274,17 @@ export class AgentSyncKnowhowWeb {
       // Create a promise that tracks finalization
       this.finalizationPromise = (async () => {
         try {
+          // Flush any in-flight thread update before sending the completion call.
+          // This prevents the race where a "inProgress: true" update overtakes
+          // the "inProgress: false" finalization call.
+          if (this.pendingThreadUpdatePromise) {
+            console.log(`⏳ [AgentSync] Awaiting pending thread update before finalizing...`);
+            await this.pendingThreadUpdatePromise.catch(() => {
+              // Ignore errors in the pending update — we still want to finalize
+            });
+            this.pendingThreadUpdatePromise = null;
+          }
+
           console.log(
             `Updating Knowhow chat task on completion..., ${this.knowhowTaskId}`
           );
@@ -306,6 +327,7 @@ export class AgentSyncKnowhowWeb {
     this.knowhowTaskId = undefined;
     this.eventHandlersSetup = false;
     this.finalizationPromise = null;
+    this.pendingThreadUpdatePromise = null;
   }
 
   /**

package/src/services/KnowhowClient.ts

@@ -24,6 +24,30 @@ import {
 } from "../clients";
 import { Config } from "../types";
 
+// Remote sync placeholder interfaces
+export interface CreateSessionPlaceholderRequest {
+  title?: string;
+  workerId?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface CreateSessionPlaceholderResponse {
+  sessionId: string;
+  orgId: string;
+}
+
+export interface CreateMessagePlaceholderRequest {
+  content: string;
+  agentName?: string;
+  modelName?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface CreateMessagePlaceholderResponse {
+  messageId: string;
+  taskId?: string;
+}
+
 // Chat Task interfaces
 export interface CreateMessageTaskRequest {
   messageId: string;
@@ -697,4 +721,41 @@ export class KnowhowSimpleClient {
       { headers: this.headers }
     );
   }
+
+  // ============================================
+  // Remote Sync Placeholder Methods
+  // ============================================
+
+  /**
+   * Create a bare session stub without triggering AI inference.
+   * Used by the CLI remote sync feature to establish a remote session.
+   */
+  async createSessionPlaceholder(
+    request: CreateSessionPlaceholderRequest = {}
+  ): Promise<CreateSessionPlaceholderResponse> {
+    await this.checkJwt();
+    const response = await http.post<CreateSessionPlaceholderResponse>(
+      `${this.baseUrl}/api/chat/sessions/placeholder`,
+      request,
+      { headers: this.headers }
+    );
+    return response.data;
+  }
+
+  /**
+   * Create a message placeholder in a session without triggering AI inference.
+   * Used by the CLI remote sync feature to register a message before syncing threads.
+   */
+  async createMessagePlaceholder(
+    sessionId: string,
+    request: CreateMessagePlaceholderRequest
+  ): Promise<CreateMessagePlaceholderResponse> {
+    await this.checkJwt();
+    const response = await http.post<CreateMessagePlaceholderResponse>(
+      `${this.baseUrl}/api/chat/sessions/${sessionId}/messages/placeholder`,
+      request,
+      { headers: this.headers }
+    );
+    return response.data;
+  }
 }

package/src/services/SessionManager.ts

@@ -54,6 +54,7 @@ export class SessionManager {
         sessionId: taskId,
         knowhowMessageId: taskInfo.knowhowMessageId,
         knowhowTaskId: taskInfo.knowhowTaskId,
+        chatSessionId: taskInfo.chatSessionId,
         taskId,
         agentName: taskInfo.agentName,
         initialInput: taskInfo.initialInput,
@@ -99,6 +100,7 @@ export class SessionManager {
           // Update Knowhow task fields if they exist in TaskInfo
           session.knowhowMessageId = taskInfo.knowhowMessageId;
           session.knowhowTaskId = taskInfo.knowhowTaskId;
+          session.chatSessionId = taskInfo.chatSessionId;
         }
 
         fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));