@botpress/adk 1.7.19 → 1.8.1

package/dist/index.js

@@ -654,7 +654,7 @@ var PRETTIER_CONFIG, formatCode = async (code, filepath) => {
 `));
     return code;
   }
-}, ADK_VERSION = "1.7.19", relative2 = (from, to) => {
+}, ADK_VERSION = "1.8.1", relative2 = (from, to) => {
   const fromDir = path10.dirname(from);
   const relative3 = path10.relative(fromDir, to);
   return relative3.startsWith(".") ? relative3 : `./${relative3}`;
@@ -797,7 +797,7 @@ var init_integration_action_types = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@botpress/adk",
-    version: "1.7.19",
+    version: "1.8.1",
     description: "Core ADK library for building AI agents on Botpress",
     type: "module",
     main: "dist/index.js",
@@ -844,7 +844,7 @@ var require_package = __commonJS((exports, module) => {
       "@botpress/cli": "^4.23",
       "@botpress/client": "^1.27.2",
       "@botpress/cognitive": "^0.2.0",
-      "@botpress/runtime": "^1.7.19",
+      "@botpress/runtime": "^1.8.1",
       "@botpress/sdk": "^4.18.1",
       "@bpinternal/yargs-extra": "^0.0.21",
       "@parcel/watcher": "^2.5.1",
@@ -4829,7 +4829,7 @@ class AgentProjectGenerator {
         deploy: "adk deploy"
       },
       dependencies: {
-        "@botpress/runtime": `^${"1.7.19"}`
+        "@botpress/runtime": `^${"1.8.1"}`
       },
       devDependencies: {
         typescript: "^5.9.3"
@@ -7814,10 +7814,732 @@ class TableManager {
     };
   }
 }
+// src/knowledge/manager.ts
+import crypto4 from "crypto";
+import path31 from "path";
+import fs16 from "fs/promises";
+import { glob } from "glob";
+import { Client as Client12 } from "@botpress/client";
+import { DataSource } from "@botpress/runtime";
+
+// src/knowledge/types.ts
+var KBSyncOperation;
+((KBSyncOperation2) => {
+  KBSyncOperation2["Sync"] = "sync";
+  KBSyncOperation2["Skip"] = "skip";
+})(KBSyncOperation ||= {});
+
+// src/knowledge/manager.ts
+var WellKnownTags = {
+  KNOWLEDGE: "knowledge",
+  KNOWLEDGE_BASE_NAME: "kbName",
+  KNOWLEDGE_SOURCE_ID: "sourceId",
+  KNOWLEDGE_SOURCE_TYPE: "sourceType"
+};
+function sourceTag(sourceId, field) {
+  const sanitizedId = sourceId.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+  return `source${sanitizedId}${field}`;
+}
+var WellKnownMetadata = {
+  TITLE: "title"
+};
+function isFileMetadata(metadata) {
+  return typeof metadata === "object" && metadata !== null && "hash" in metadata && typeof metadata.hash === "string" && "relPath" in metadata && typeof metadata.relPath === "string";
+}
+
+class KnowledgeManager {
+  client;
+  botId;
+  project;
+  fileHashCache = new Map;
+  constructor(options) {
+    this.botId = options.botId;
+    this.project = options.project;
+  }
+  clearHashCache() {
+    this.fileHashCache.clear();
+  }
+  async getClient() {
+    if (!this.client) {
+      const credentials = await auth.getActiveCredentials();
+      this.assertBotId("initialize client");
+      this.client = new Client12({
+        token: credentials.token,
+        apiUrl: credentials.apiUrl,
+        botId: this.botId,
+        headers: {
+          "x-multiple-integrations": "true"
+        }
+      });
+    }
+    return this.client;
+  }
+  assertBotId(operation) {
+    if (!this.botId) {
+      throw new Error(`Operation "${operation}" requires a bot ID. ` + "Please deploy your agent first or create agent.json with botId and workspaceId.");
+    }
+  }
+  formatError(error) {
+    if (!(error instanceof Error)) {
+      return String(error);
+    }
+    let message = error.message;
+    if ("response" in error && error.response !== null && typeof error.response === "object" && "data" in error.response) {
+      message += ` - API: ${JSON.stringify(error.response.data)}`;
+    }
+    return message;
+  }
+  getLocalKnowledgeBases() {
+    const kbs = [];
+    for (const kbRef of this.project.knowledge) {
+      const definition = kbRef.definition;
+      kbs.push({
+        name: definition.name,
+        description: definition.description,
+        sourceCount: definition.sources?.length || 0
+      });
+    }
+    return kbs;
+  }
+  computeContentHash(fileHashes) {
+    const sortedEntries = Object.entries(fileHashes).sort(([a], [b]) => a.localeCompare(b));
+    const combined = sortedEntries.map(([filePath, hash]) => `${filePath}:${hash}`).join(`
+`);
+    return crypto4.createHash("sha256").update(combined).digest("hex");
+  }
+  async listRemoteKnowledgeBases() {
+    const client = await this.getClient();
+    const kbs = [];
+    let nextToken;
+    do {
+      const response = await client.listKnowledgeBases({ nextToken });
+      kbs.push(...response.knowledgeBases);
+      nextToken = response.meta.nextToken;
+    } while (nextToken);
+    return kbs;
+  }
+  async findRemoteKB(name) {
+    const kbs = await this.listRemoteKnowledgeBases();
+    return kbs.find((kb) => kb.name === name);
+  }
+  async createKnowledgeBase(name) {
+    const client = await this.getClient();
+    await client.createKnowledgeBase({ name });
+    const created = await this.findRemoteKB(name);
+    if (!created) {
+      throw new Error(`Failed to find KB "${name}" after creation`);
+    }
+    return created;
+  }
+  async getOrphanedKBs() {
+    const localKbNames = this.getLocalKnowledgeBases().map((kb) => kb.name);
+    const remoteKbs = await this.listRemoteKnowledgeBases();
+    return remoteKbs.filter((kb) => !localKbNames.includes(kb.name));
+  }
+  async getOrphanedSources(kbName, localSourceIds) {
+    const client = await this.getClient();
+    const tags = {
+      [WellKnownTags.KNOWLEDGE]: "true",
+      [WellKnownTags.KNOWLEDGE_BASE_NAME]: kbName
+    };
+    const files = [];
+    let nextToken;
+    do {
+      const response = await client.listFiles({ tags, nextToken });
+      files.push(...response.files);
+      nextToken = response.meta.nextToken;
+    } while (nextToken);
+    const filesBySourceId = new Map;
+    for (const file of files) {
+      const sourceId = file.tags?.[WellKnownTags.KNOWLEDGE_SOURCE_ID] || file.metadata?.sourceId;
+      if (sourceId) {
+        filesBySourceId.set(sourceId, (filesBySourceId.get(sourceId) || 0) + 1);
+      }
+    }
+    const orphaned = [];
+    for (const [sourceId, fileCount] of filesBySourceId) {
+      if (!localSourceIds.includes(sourceId)) {
+        orphaned.push({ sourceId, fileCount });
+      }
+    }
+    return orphaned;
+  }
+  async deleteOrphanedSource(kbName, sourceId) {
+    const client = await this.getClient();
+    const tags = {
+      [WellKnownTags.KNOWLEDGE]: "true",
+      [WellKnownTags.KNOWLEDGE_BASE_NAME]: kbName,
+      [WellKnownTags.KNOWLEDGE_SOURCE_ID]: sourceId
+    };
+    const files = await this.listExistingFiles(client, tags);
+    console.log(`     Deleting ${files.length} files from orphaned source "${sourceId}"...`);
+    const results = await Promise.allSettled(files.map((f) => client.deleteFile({ id: f.id })));
+    const deletedFiles = results.filter((r) => r.status === "fulfilled").length;
+    const errors = results.filter((r) => r.status === "rejected").map((r) => String(r.reason));
+    return { deletedFiles, errors };
+  }
+  async cleanupSourceTags(kbId, kbName, sourceIds, existingTags) {
+    const client = await this.getClient();
+    const newTags = { ...existingTags };
+    for (const sourceId of sourceIds) {
+      const sanitizedId = sourceId.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+      newTags[`source${sanitizedId}hash`] = "";
+      newTags[`source${sanitizedId}lastupdatedat`] = "";
+    }
+    await client.updateKnowledgeBase({ id: kbId, name: kbName, tags: newTags });
+  }
+  async deleteKnowledgeBase(kbId, kbName) {
+    const client = await this.getClient();
+    const tags = {
+      [WellKnownTags.KNOWLEDGE]: "true",
+      [WellKnownTags.KNOWLEDGE_BASE_NAME]: kbName
+    };
+    console.log(`     Listing files for KB "${kbName}"...`);
+    const files = await this.listExistingFiles(client, tags);
+    console.log(`     Found ${files.length} files to delete`);
+    const results = await Promise.allSettled(files.map((file) => client.deleteFile({ id: file.id })));
+    const deletedFiles = results.filter((r) => r.status === "fulfilled").length;
+    console.log(`     Deleting KB "${kbName}"...`);
+    await client.deleteKnowledgeBase({ id: kbId });
+    return { deletedFiles };
+  }
+  getRemoteSourceHash(kb, sourceId) {
+    return kb.tags?.[sourceTag(sourceId, "hash")];
+  }
+  async updateSourceHash(kbId, kbName, sourceId, hash, existingTags) {
+    const client = await this.getClient();
+    await client.updateKnowledgeBase({
+      id: kbId,
+      name: kbName,
+      tags: {
+        ...existingTags,
+        [sourceTag(sourceId, "hash")]: hash,
+        [sourceTag(sourceId, "lastupdatedat")]: new Date().toISOString()
+      }
+    });
+  }
+  computeConfigHash(config) {
+    const sortedConfig = JSON.stringify(config, Object.keys(config).sort());
+    return crypto4.createHash("sha256").update(sortedConfig).digest("hex");
+  }
+  async syncWebsiteSource(kbName, force) {
+    const client = await this.getClient();
+    const response = await client.createWorkflow({
+      name: "builtin_knowledge_indexing",
+      input: { kbName, force },
+      status: "pending",
+      timeoutAt: new Date(Date.now() + 180 * 60 * 1000).toISOString()
+    });
+    return { workflowId: response.workflow.id };
+  }
+  hasWebsiteSources(kbName) {
+    const kbRef = this.project.knowledge.find((k) => k.definition.name === kbName);
+    if (!kbRef)
+      return false;
+    return kbRef.definition.sources?.some((s) => DataSource.isWebsite(s)) || false;
+  }
+  getKBsWithWebsiteSources() {
+    return this.project.knowledge.filter((k) => k.definition.sources?.some((s) => DataSource.isWebsite(s))).map((k) => k.definition.name);
+  }
+  async computeDirectorySourceHash(directoryPath, filterFn) {
+    const fileHashes = await this.scanLocalFileHashes(directoryPath, filterFn);
+    return this.computeContentHash(fileHashes);
+  }
+  async createSyncPlan() {
+    const localKbs = this.getLocalKnowledgeBases();
+    const remoteKbs = await this.listRemoteKnowledgeBases();
+    const items = [];
+    for (const kb of localKbs) {
+      const kbRef = this.project.knowledge.find((k) => k.definition.name === kb.name);
+      if (!kbRef)
+        continue;
+      const remoteKb = remoteKbs.find((r) => r.name === kb.name);
+      if (!remoteKb) {
+        const sources2 = (kbRef.definition.sources || []).map((source) => ({
+          sourceId: source.id,
+          sourceType: DataSource.isDirectory(source) ? "directory" : "website",
+          needsSync: true,
+          reason: "New KB"
+        }));
+        items.push({
+          operation: "sync" /* Sync */,
+          kb,
+          reason: "Knowledge base not found remotely",
+          needsCreation: true,
+          sources: sources2
+        });
+        continue;
+      }
+      const sources = [];
+      let hasChanges = false;
+      for (const source of kbRef.definition.sources || []) {
+        const remoteHash = this.getRemoteSourceHash(remoteKb, source.id);
+        if (DataSource.isDirectory(source)) {
+          const localHash = await this.computeDirectorySourceHash(source.directoryPath, source.filterFn);
+          if (!remoteHash) {
+            sources.push({
+              sourceId: source.id,
+              sourceType: "directory",
+              needsSync: true,
+              reason: "First-time sync"
+            });
+            hasChanges = true;
+          } else if (localHash !== remoteHash) {
+            const fileChanges = await this.detectDirectorySourceChanges(kb.name, source);
+            sources.push({
+              sourceId: source.id,
+              sourceType: "directory",
+              needsSync: true,
+              reason: "Content changed",
+              fileChanges
+            });
+            hasChanges = true;
+          } else {
+            sources.push({
+              sourceId: source.id,
+              sourceType: "directory",
+              needsSync: false,
+              reason: "No changes"
+            });
+          }
+        } else if (DataSource.isWebsite(source)) {
+          const config = source.getConfig();
+          const localHash = this.computeConfigHash(config);
+          if (!remoteHash) {
+            sources.push({
+              sourceId: source.id,
+              sourceType: "website",
+              needsSync: true,
+              reason: "First-time crawl"
+            });
+            hasChanges = true;
+          } else if (localHash !== remoteHash) {
+            sources.push({
+              sourceId: source.id,
+              sourceType: "website",
+              needsSync: true,
+              reason: "Config changed - needs recrawl"
+            });
+            hasChanges = true;
+          } else {
+            sources.push({
+              sourceId: source.id,
+              sourceType: "website",
+              needsSync: false,
+              reason: "No config changes"
+            });
+          }
+        }
+      }
+      const localSourceIds = (kbRef.definition.sources || []).map((s) => s.id);
+      const orphaned = await this.getOrphanedSources(kb.name, localSourceIds);
+      const orphanedSourceStatuses = orphaned.map((o) => ({
+        sourceId: o.sourceId,
+        fileCount: o.fileCount,
+        willDelete: true
+      }));
+      const hasOrphanedSources = orphanedSourceStatuses.length > 0;
+      items.push({
+        operation: hasChanges || hasOrphanedSources ? "sync" /* Sync */ : "skip" /* Skip */,
+        kb,
+        reason: hasOrphanedSources ? hasChanges ? "Sources need sync and orphaned sources to remove" : "Orphaned sources to remove" : hasChanges ? "Sources need sync" : "No changes",
+        sources,
+        orphanedSources: hasOrphanedSources ? orphanedSourceStatuses : undefined
+      });
+    }
+    const toSync = items.filter((i) => i.operation === "sync" /* Sync */).length;
+    const toSkip = items.filter((i) => i.operation === "skip" /* Skip */).length;
+    let sourcesToSync = 0;
+    let sourcesToSkip = 0;
+    let orphanedSourcesToDelete = 0;
+    for (const item of items) {
+      for (const source of item.sources || []) {
+        if (source.needsSync) {
+          sourcesToSync++;
+        } else {
+          sourcesToSkip++;
+        }
+      }
+      orphanedSourcesToDelete += item.orphanedSources?.length || 0;
+    }
+    return {
+      items,
+      toSync,
+      toSkip,
+      hasChanges: toSync > 0,
+      sourcesToSync,
+      sourcesToSkip,
+      orphanedSourcesToDelete
+    };
+  }
+  async detectDirectorySourceChanges(kbName, source) {
+    const client = await this.getClient();
+    const added = [];
+    const deleted = [];
+    const modified = [];
+    const tags = {
+      [WellKnownTags.KNOWLEDGE]: "true",
+      [WellKnownTags.KNOWLEDGE_SOURCE_ID]: source.id,
+      [WellKnownTags.KNOWLEDGE_BASE_NAME]: kbName
+    };
+    const remoteFiles = await this.listExistingFiles(client, tags);
+    const remoteHashes = {};
+    for (const file of remoteFiles) {
+      if (isFileMetadata(file.metadata)) {
+        remoteHashes[file.metadata.relPath] = file.metadata.hash;
+      }
+    }
+    const localHashes = await this.scanLocalFileHashes(source.directoryPath, source.filterFn);
+    for (const [relPath, hash] of Object.entries(localHashes)) {
+      if (!remoteHashes[relPath]) {
+        added.push(relPath);
+      } else if (remoteHashes[relPath] !== hash) {
+        modified.push(relPath);
+      }
+    }
+    for (const relPath of Object.keys(remoteHashes)) {
+      if (!localHashes[relPath]) {
+        deleted.push(relPath);
+      }
+    }
+    return { added, deleted, modified };
+  }
+  async scanLocalFileHashes(directoryPath, filterFn) {
+    const projectDir = this.project.path;
+    const directory = path31.resolve(projectDir, directoryPath);
+    if (this.fileHashCache.has(directory)) {
+      return this.fileHashCache.get(directory);
+    }
+    const files = glob.sync(directory + "/**/*.*", { absolute: true, nodir: true }).filter((file) => !filterFn || filterFn(file));
+    const hashes = {};
+    for (const file of files) {
+      const relPath = path31.relative(directory, file);
+      const content = await fs16.readFile(file);
+      hashes[relPath] = crypto4.createHash("sha256").update(content).digest("hex");
+    }
+    this.fileHashCache.set(directory, hashes);
+    return hashes;
+  }
+  async executeSync(plan, options = {}) {
+    this.assertBotId("sync knowledge bases");
+    const client = await this.getClient();
+    const result = {
+      synced: [],
+      skipped: [],
+      failed: [],
+      websiteSyncs: []
+    };
+    for (const item of plan.items) {
+      if (item.operation === "skip" /* Skip */ && !options.force) {
+        result.skipped.push({ name: item.kb.name, reason: item.reason });
+        continue;
+      }
+      try {
+        console.log(`Syncing KB "${item.kb.name}"...`);
+        const kbRef = this.project.knowledge.find((k) => k.definition.name === item.kb.name);
+        if (!kbRef) {
+          throw new Error(`KB "${item.kb.name}" not found in project`);
+        }
+        let remoteKb = await this.findRemoteKB(item.kb.name);
+        if (!remoteKb) {
+          console.log(`  Creating KB "${item.kb.name}"...`);
+          remoteKb = await this.createKnowledgeBase(item.kb.name);
+        }
+        if (item.orphanedSources && item.orphanedSources.length > 0) {
+          console.log(`  Removing ${item.orphanedSources.length} orphaned source(s)...`);
+          const deletedSourceIds = [];
+          for (const orphaned of item.orphanedSources) {
+            const { deletedFiles, errors } = await this.deleteOrphanedSource(item.kb.name, orphaned.sourceId);
+            console.log(`     ✕ ${orphaned.sourceId}: ${deletedFiles} files deleted`);
+            if (errors.length === 0) {
+              deletedSourceIds.push(orphaned.sourceId);
+            } else {
+              console.warn(`     Warning: ${errors.length} errors during deletion`);
+            }
+          }
+          if (deletedSourceIds.length > 0) {
+            const freshKb = await this.findRemoteKB(item.kb.name);
+            if (freshKb) {
+              await this.cleanupSourceTags(freshKb.id, item.kb.name, deletedSourceIds, freshKb.tags || {});
+              remoteKb = freshKb;
+            }
+          }
+        }
+        const syncOutput = {
+          processed: 0,
+          added: [],
+          updated: [],
+          deleted: [],
+          errors: []
+        };
+        const sourcesToSync = options.force ? item.sources || [] : (item.sources || []).filter((s) => s.needsSync);
+        const directorySourcesToSync = sourcesToSync.filter((s) => s.sourceType === "directory");
+        const websiteSourcesToSync = sourcesToSync.filter((s) => s.sourceType === "website");
+        for (const sourceStatus of directorySourcesToSync) {
+          const source = kbRef.definition.sources?.find((s) => s.id === sourceStatus.sourceId);
+          if (!source || !DataSource.isDirectory(source))
+            continue;
+          console.log(`  Syncing directory source "${source.id}"...`);
+          const sourceOutput = await this.syncDirectorySource(client, item.kb.name, source.id, source.directoryPath, source.filterFn, options.force || false);
+          syncOutput.processed += sourceOutput.processed;
+          syncOutput.added.push(...sourceOutput.added);
+          syncOutput.updated.push(...sourceOutput.updated);
+          syncOutput.deleted.push(...sourceOutput.deleted);
+          syncOutput.errors.push(...sourceOutput.errors);
+          const sourceHash = await this.computeDirectorySourceHash(source.directoryPath, source.filterFn);
+          await this.updateSourceHash(remoteKb.id, item.kb.name, source.id, sourceHash, remoteKb.tags);
+        }
+        if (websiteSourcesToSync.length > 0) {
+          try {
+            console.log(`  Triggering website sync workflow for ${websiteSourcesToSync.length} source(s)...`);
+            const { workflowId } = await this.syncWebsiteSource(item.kb.name, options.force || false);
+            result.websiteSyncs.push({ kbName: item.kb.name, workflowId });
+            for (const sourceStatus of websiteSourcesToSync) {
+              const source = kbRef.definition.sources?.find((s) => s.id === sourceStatus.sourceId);
+              if (!source || !DataSource.isWebsite(source))
+                continue;
+              const config = source.getConfig();
+              const configHash = this.computeConfigHash(config);
+              await this.updateSourceHash(remoteKb.id, item.kb.name, source.id, configHash, remoteKb.tags);
+            }
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            console.warn(`  Warning: Could not trigger website sync: ${errorMsg}`);
+          }
+        }
+        result.synced.push({ name: item.kb.name, result: syncOutput });
+      } catch (error) {
+        const errorMessage = this.formatError(error);
+        console.error(`Failed to sync KB "${item.kb.name}": ${errorMessage}`);
+        result.failed.push({ name: item.kb.name, error: errorMessage });
+      }
+    }
+    return result;
+  }
+  async syncDirectorySource(client, kbName, sourceId, directoryPath, filterFn, force) {
+    const projectDir = this.project.path;
+    const directory = path31.resolve(projectDir, directoryPath);
+    if (!directory.startsWith(projectDir)) {
+      throw new Error("Directory path must be within the agent's directory");
+    }
+    const tags = {
+      [WellKnownTags.KNOWLEDGE]: "true",
+      [WellKnownTags.KNOWLEDGE_SOURCE_ID]: sourceId,
+      [WellKnownTags.KNOWLEDGE_SOURCE_TYPE]: "directory",
+      [WellKnownTags.KNOWLEDGE_BASE_NAME]: kbName
+    };
+    let allFiles = glob.sync(directory + "/**/*.*", { absolute: true, nodir: true }).filter((file) => {
+      if (filterFn) {
+        try {
+          return filterFn(file);
+        } catch {
+          return false;
+        }
+      }
+      return true;
+    }).map((f) => ({
+      abs: f,
+      rel: path31.relative(directory, f),
+      name: path31.basename(f)
+    }));
+    console.log(`  Found ${allFiles.length} files in ${directoryPath}`);
+    const cachedHashes = await this.scanLocalFileHashes(directoryPath, filterFn);
+    const existingFiles = await this.listExistingFiles(client, tags);
+    console.log(`  Found ${existingFiles.length} existing files in Botpress`);
+    const toRemove = existingFiles.filter((f) => !allFiles.find((af) => af.rel === f.metadata?.relPath));
+    const toAdd = allFiles.filter((af) => !existingFiles.find((f) => f.metadata?.relPath === af.rel));
+    const toUpdate = allFiles.filter((af) => existingFiles.find((f) => f.metadata?.relPath === af.rel));
+    const output = {
+      processed: allFiles.length,
+      added: [],
+      updated: [],
+      deleted: [],
+      errors: []
+    };
+    for (const file of toRemove) {
+      try {
+        await client.deleteFile({ id: file.id });
+        output.deleted.push({
+          file: file.id,
+          name: file.key,
+          hash: file.metadata?.hash ?? "",
+          size: file.size ?? -1
+        });
+      } catch (error) {
+        output.errors.push({
+          file: file.id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    for (const local of toAdd) {
+      const result = await this.upsertFile(client, local, sourceId, tags, force, cachedHashes[local.rel]);
+      if (result) {
+        output.added.push(result);
+      }
+    }
+    for (const local of toUpdate) {
+      const result = await this.upsertFile(client, local, sourceId, tags, force, cachedHashes[local.rel]);
+      if (result) {
+        output.updated.push(result);
+      }
+    }
+    console.log(`  Synced: ${output.added.length} added, ${output.updated.length} updated, ${output.deleted.length} deleted`);
+    return output;
+  }
+  async listExistingFiles(client, tags) {
+    const files = [];
+    let nextToken;
+    do {
+      const response = await client.listFiles({ tags, nextToken });
+      files.push(...response.files.map((f) => ({
+        id: f.id,
+        key: f.key,
+        size: f.size,
+        metadata: isFileMetadata(f.metadata) ? f.metadata : undefined
+      })));
+      nextToken = response.meta.nextToken;
+    } while (nextToken);
+    return files;
+  }
+  async upsertFile(client, local, sourceId, tags, force, cachedHash) {
+    const key = `data_source://directory/${sourceId}/${local.rel}`;
+    const content = await fs16.readFile(local.abs);
+    const hash = cachedHash ?? crypto4.createHash("sha256").update(content).digest("hex");
+    try {
+      const { file } = await client.getFile({ id: key });
+      if (!force && isFileMetadata(file.metadata) && file.metadata.hash === hash) {
+        return null;
+      }
+    } catch {}
+    const title = path31.basename(local.name, path31.extname(local.name));
+    const metadata = {
+      hash,
+      sourceId,
+      sourceType: "directory",
+      relPath: local.rel,
+      [WellKnownMetadata.TITLE]: title
+    };
+    const uploaded = await client.uploadFile({
+      key,
+      content,
+      accessPolicies: [],
+      tags,
+      index: true,
+      metadata
+    });
+    return {
+      file: uploaded.file.id,
+      hash,
+      name: key,
+      size: uploaded.file.size ?? -1
+    };
+  }
+}
+// src/knowledge/sync-formatter.ts
+import { readFileSync } from "fs";
+import { join as join7 } from "path";
+var getAdkVersion = () => {
+  try {
+    const packageJson = require_package();
+    return packageJson.version;
+  } catch {
+    try {
+      const adkPackagePath = join7(process.cwd(), "node_modules/@botpress/adk/package.json");
+      const pkg = JSON.parse(readFileSync(adkPackagePath, "utf-8"));
+      return pkg.version;
+    } catch {
+      return "unknown";
+    }
+  }
+};
+function pluralize(count, word) {
+  return `${count} ${word}${count !== 1 ? "s" : ""}`;
+}
+
+class KBSyncFormatter {
+  static format(plan, kbsWithWebsites = []) {
+    const sections = [];
+    sections.push("");
+    sections.push(" ▄▀█ █▀▄ █▄▀  Botpress ADK");
+    sections.push(` █▀█ █▄▀ █░█  v${getAdkVersion()}`);
+    sections.push("");
+    sections.push("Knowledge Base Sync");
+    sections.push("");
+    if (!plan.hasChanges) {
+      sections.push("✓ All knowledge bases are up to date.");
+      sections.push("");
+      return sections.join(`
+`);
+    }
+    const kbsToSync = plan.items.filter((i) => i.operation === "sync" /* Sync */);
+    const kbsToSkip = plan.items.filter((i) => i.operation === "skip" /* Skip */);
+    if (kbsToSync.length > 0) {
+      sections.push(`Knowledge Bases to Sync:
+`);
+      for (const item of kbsToSync) {
+        const icon = item.needsCreation ? "+" : "~";
+        const action = item.needsCreation ? "CREATE" : "UPDATE";
+        sections.push(`  ${icon} ${item.kb.name}`);
+        sections.push(`    Action: ${action}`);
+        sections.push(`    Reason: ${item.reason}`);
+        if (item.sources && item.sources.length > 0) {
+          sections.push("    Sources:");
+          for (const source of item.sources) {
+            if (source.needsSync) {
+              const typeLabel = source.sourceType === "directory" ? "\uD83D\uDCC1" : "\uD83C\uDF10";
+              sections.push(`      ${typeLabel} ${source.sourceId} (${source.sourceType})`);
+              sections.push(`         ${source.reason}`);
+              if (source.fileChanges) {
+                const { added, modified, deleted } = source.fileChanges;
+                if (added.length > 0) {
+                  sections.push(`         + ${pluralize(added.length, "file")} to add`);
+                }
+                if (modified.length > 0) {
+                  sections.push(`         ~ ${pluralize(modified.length, "file")} to update`);
+                }
+                if (deleted.length > 0) {
+                  sections.push(`         - ${pluralize(deleted.length, "file")} to delete`);
+                }
+              }
+            }
+          }
+        }
+        sections.push("");
+      }
+    }
+    if (kbsToSkip.length > 0) {
+      sections.push(`Knowledge Bases Already Up to Date:
+`);
+      for (const item of kbsToSkip) {
+        sections.push(`  ✓ ${item.kb.name}`);
+      }
+      sections.push("");
+    }
+    if (kbsWithWebsites.length > 0) {
+      sections.push("⚠️  Website Sources");
+      sections.push("   Website crawling will run asynchronously in the bot runtime.");
+      sections.push(`   KBs with websites: ${kbsWithWebsites.join(", ")}`);
+      sections.push("");
+    }
+    sections.push(`Summary of Actions
+`);
+    if (plan.toSync > 0) {
+      sections.push(`  • Sync: ${pluralize(plan.toSync, "knowledge base")}`);
+    }
+    if (plan.toSkip > 0) {
+      sections.push(`  • Skip: ${pluralize(plan.toSkip, "knowledge base")} (up to date)`);
+    }
+    sections.push(`  • Sources: ${plan.sourcesToSync} to sync, ${plan.sourcesToSkip} up to date`);
+    sections.push("");
+    return sections.join(`
+`);
+  }
+}
 // src/file-watcher/watcher.ts
 import { watch as watch2, readdirSync as readdirSync2 } from "fs";
 import { EventEmitter as EventEmitter3 } from "events";
-import { join as join7, relative as relative3 } from "path";
+import { join as join8, relative as relative3 } from "path";
 import { existsSync as existsSync6 } from "fs";
 
 class FileWatcher2 extends EventEmitter3 {
@@ -7835,12 +8557,12 @@ class FileWatcher2 extends EventEmitter3 {
   start() {
     const rootFiles = ["package.json", "agent.json", "agent.config.ts"];
     for (const file of rootFiles) {
-      const filePath = join7(this.projectPath, file);
+      const filePath = join8(this.projectPath, file);
       if (existsSync6(filePath)) {
         this.watchFile(filePath);
       }
     }
-    const srcPath = join7(this.projectPath, "src");
+    const srcPath = join8(this.projectPath, "src");
     if (existsSync6(srcPath)) {
       this.initializeDirectoryState(srcPath);
       this.watchDirectory(srcPath);
@@ -7850,7 +8572,7 @@ class FileWatcher2 extends EventEmitter3 {
     try {
       const entries = readdirSync2(dirPath, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = join7(dirPath, entry.name);
+        const fullPath = join8(dirPath, entry.name);
         if (entry.isDirectory()) {
           this.initializeDirectoryState(fullPath);
         } else if (entry.isFile()) {
@@ -7880,7 +8602,7 @@ class FileWatcher2 extends EventEmitter3 {
     try {
       const watcher = watch2(dirPath, { recursive: true, persistent: true }, (_eventType, filename) => {
         if (filename) {
-          const fullPath = join7(dirPath, filename);
+          const fullPath = join8(dirPath, filename);
           this.handleFileChange(fullPath);
         }
       });
@@ -7954,14 +8676,14 @@ class FileWatcher2 extends EventEmitter3 {
   }
 }
 // src/preflight/checker.ts
-import { Client as Client12 } from "@botpress/client";
-import path31 from "path";
+import { Client as Client13 } from "@botpress/client";
+import path32 from "path";
 
 // src/preflight/types.ts
 function hasIntegrationChanges(integrations) {
   return integrations.toInstall.length > 0 || integrations.toRemove.length > 0 || integrations.toUpdate.length > 0;
 }
-function pluralize(count, word) {
+function pluralize2(count, word) {
   return `${count} ${word}${count > 1 ? "s" : ""}`;
 }
 
@@ -8012,16 +8734,16 @@ class AgentConfigSyncManager {
 }
 
 // src/preflight/formatter.ts
-import { readFileSync } from "fs";
-import { join as join8 } from "path";
-var getAdkVersion = () => {
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join9 } from "path";
+var getAdkVersion2 = () => {
   try {
     const packageJson = require_package();
     return packageJson.version;
   } catch {
     try {
-      const adkPackagePath = join8(process.cwd(), "node_modules/@botpress/adk/package.json");
-      const pkg = JSON.parse(readFileSync(adkPackagePath, "utf-8"));
+      const adkPackagePath = join9(process.cwd(), "node_modules/@botpress/adk/package.json");
+      const pkg = JSON.parse(readFileSync2(adkPackagePath, "utf-8"));
       return pkg.version;
     } catch {
       return "unknown";
@@ -8034,7 +8756,7 @@ class PreflightFormatter {
     const sections = [];
     sections.push("");
     sections.push(" ▄▀█ █▀▄ █▄▀  Botpress ADK");
-    sections.push(` █▀█ █▄▀ █░█  v${getAdkVersion()}`);
+    sections.push(` █▀█ █▄▀ █░█  v${getAdkVersion2()}`);
     sections.push("");
     sections.push("Running preflight checks...");
     sections.push("");
@@ -8108,16 +8830,16 @@ class PreflightFormatter {
     const update = result.integrations.toUpdate.length;
     const agentConfig = result.agentConfig.length;
     if (install > 0) {
-      sections.push(`  • Install: ${pluralize(install, "integration")}`);
+      sections.push(`  • Install: ${pluralize2(install, "integration")}`);
     }
     if (remove > 0) {
-      sections.push(`  • Remove:  ${pluralize(remove, "integration")}`);
+      sections.push(`  • Remove:  ${pluralize2(remove, "integration")}`);
     }
     if (update > 0) {
-      sections.push(`  • Update:  ${pluralize(update, "integration")}`);
+      sections.push(`  • Update:  ${pluralize2(update, "integration")}`);
     }
     if (agentConfig > 0) {
-      sections.push(`  • Agent config: ${pluralize(agentConfig, "change")}`);
+      sections.push(`  • Agent config: ${pluralize2(agentConfig, "change")}`);
     }
     sections.push("");
     return sections.join(`
@@ -8169,7 +8891,7 @@ class PreflightChecker {
       if (!workspaceId) {
         throw new Error('No workspace ID found. Please login with "adk login"');
       }
-      this.client = new Client12({
+      this.client = new Client13({
         token: credentials.token,
         apiUrl: credentials.apiUrl,
         workspaceId,
@@ -8295,16 +9017,16 @@ class PreflightChecker {
       const integrationSyncer = new IntegrationSyncManager(this.projectPath);
       const syncResult = await integrationSyncer.applySyncPlan(integrationResults, botId);
       if (syncResult.installed > 0) {
-        options?.onSuccess?.(`Installed ${pluralize(syncResult.installed, "integration")}`);
+        options?.onSuccess?.(`Installed ${pluralize2(syncResult.installed, "integration")}`);
       }
       if (syncResult.updated > 0) {
-        options?.onSuccess?.(`Updated ${pluralize(syncResult.updated, "integration")}`);
+        options?.onSuccess?.(`Updated ${pluralize2(syncResult.updated, "integration")}`);
       }
       if (syncResult.removed > 0) {
-        options?.onSuccess?.(`Removed ${pluralize(syncResult.removed, "integration")}`);
+        options?.onSuccess?.(`Removed ${pluralize2(syncResult.removed, "integration")}`);
       }
       if (syncResult.failed > 0) {
-        options?.onError?.(`Failed to sync ${pluralize(syncResult.failed, "integration")}`);
+        options?.onError?.(`Failed to sync ${pluralize2(syncResult.failed, "integration")}`);
         for (const { alias, error } of syncResult.errors) {
           options?.onError?.(`  ${alias}: ${error}`);
         }
@@ -8317,7 +9039,7 @@ class PreflightChecker {
     options?.onProgress?.("Regenerating bot project...");
     await generateBotProject({
       projectPath: this.projectPath,
-      outputPath: path31.join(this.projectPath, ".adk", "bot")
+      outputPath: path32.join(this.projectPath, ".adk", "bot")
     });
     options?.onSuccess?.("Bot project regenerated");
   }
@@ -8344,6 +9066,9 @@ export {
   ProjectState,
   PreflightFormatter,
   PreflightChecker,
+  KnowledgeManager,
+  KBSyncOperation,
+  KBSyncFormatter,
   InterfaceParser,
   InterfaceOperations,
   InterfaceManager,
@@ -8370,5 +9095,5 @@ export {
   AgentProject
 };
 
-//# debugId=903A2AC825E269AB64756E2164756E21
+//# debugId=D1FBF4E6E55AF89264756E2164756E21
 //# sourceMappingURL=index.js.map