@zerowidth/workbench-sdk 2.0.0-alpha.0 → 2.1.1

package/nodes/semantic-search/semantic-search.process.js

@@ -1,44 +1,67 @@
 export default async ({inputs, settings, config, nodeConfig}) => {
     try {
-        // Get knowledge base and OpenAI integrations
-        const knowledgeBase = config.integrations?.knowledgeBase || config.integrations?.sqlite;
-        const openai = config.integrations?.openai;
-        
+        // Resolve which knowledge base to search. Node-level binding: a
+        // `knowledge_base` handle wired in from a Knowledge Base node names a
+        // specific KB by uuid, resolved to a per-KB integration the host keyed
+        // as config.integrations.knowledgeBases[uuid]. Falls back to the
+        // flow-global KB (config.integrations.knowledgeBase / .sqlite) so
+        // existing single-KB flows keep working. See ADR 0023.
+        const kbRef = inputs.knowledge_base;
+        const kbByUuid =
+            kbRef && kbRef.uuid
+                ? config.integrations?.[`knowledgeBase:${kbRef.uuid}`]
+                : null;
+        const knowledgeBase =
+            kbByUuid ||
+            config.integrations?.knowledgeBase ||
+            config.integrations?.sqlite;
+        const openrouter = config.integrations?.openrouter;
+
         if (!knowledgeBase) {
             throw new Error("Knowledge base integration not found. Make sure a knowledge database is available.");
         }
-        
-        if (!openai) {
-            throw new Error("OpenAI integration not found. Semantic search requires OpenAI API key for embeddings.");
+
+        if (!openrouter) {
+            throw new Error("OpenRouter integration not found. Semantic search requires an OpenRouter API key for query embeddings.");
         }
 
-        const { 
-            query, 
-            limit = 10, 
-            similarity_threshold = 0.7, 
-            document_id = null 
+        const {
+            query,
+            limit = 10,
+            // Default 0 (matches the node config) — return matches ranked by
+            // similarity rather than silently filtering everything below 0.7.
+            similarity_threshold = 0,
+            document_id = null
         } = inputs;
-        
+
         const { embedding_model = null } = settings;
 
         if (!query || typeof query !== 'string') {
             throw new Error("Query is required and must be a string");
         }
 
-        // Get the embedding model to use
+        // Embedding model: node-setting override, else the model the KB was
+        // indexed with (KB-owned — query + index MUST agree so semanticSearch
+        // can filter `embedding_model = ?`). OpenRouter model ids are
+        // namespaced, e.g. "openai/text-embedding-3-small".
         let modelToUse = embedding_model;
         if (!modelToUse) {
             try {
                 modelToUse = await knowledgeBase.getEmbeddingModel();
             } catch (error) {
                 console.warn('[WARN] Failed to get embedding model from knowledge base, using default:', error.message);
-                modelToUse = 'text-embedding-3-small';
+                modelToUse = 'openai/text-embedding-3-small';
             }
         }
 
-        // Create embedding for the query
-        const embeddingResponse = await openai.createEmbedding(query, modelToUse);
-        const queryEmbedding = embeddingResponse.data[0].embedding;
+        // Embed the query via OpenRouter. Returns { embedding, embeddings,
+        // dimensions, model, usage, cost_total?, cost_itemized? }.
+        const embeddingResponse = await openrouter.createEmbedding(
+            { model: modelToUse, input: query },
+            nodeConfig,
+            config
+        );
+        const queryEmbedding = embeddingResponse.embedding;
 
         // Perform semantic search
         const searchOptions = {

package/nodes/tool/tool.config.json

@@ -6,6 +6,7 @@
   "category": "messages",
   "custom_render_height": 200,
   "is_constant": true,
+  "is_plugin": true,
   "is_resizable": true,
   "inputs": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.0.0-alpha.0",
+  "version": "2.1.1",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",
@@ -8,17 +8,21 @@
     "js-tiktoken": "^1.0.21",
     "openai": "^4.92.1",
     "sqlite-vec": "^0.1.7-alpha.2",
-    "sqlite3": "^5.1.7",
     "tiktoken": "^1.0.22",
     "uuid": "^11.1.0"
   },
   "repository": "https://github.com/zerowidth-ai/workbench-sdk",
-  "description": "Workbench SDK — execute Workbench-authored flows in production. Successor to the zv1 package; see https://zerowidth.ai for the design surface.",
+  "description": "Workbench SDK \u2014 execute Workbench-authored flows in production. Successor to the zv1 package; see https://zerowidth.ai for the design surface.",
   "main": "./src/index.js",
-  "files": ["src/", "nodes/", "types/", "LICENSE", "README.md"],
+  "files": [
+    "src/",
+    "nodes/",
+    "types/",
+    "LICENSE",
+    "README.md"
+  ],
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -29,7 +33,8 @@
   "scripts": {
     "test-nodes": "node tests/test.all-nodes.js",
     "test-flows": "node tests/test.flows.js",
-    "test-flow": "node tests/test.flows.js"
+    "test-flow": "node tests/test.flows.js",
+    "test-kb": "node tests/test.kb-search.js && node tests/test.kb-graph.js"
   },
   "author": "Peter Binggeser @ ZeroWidth, LLC",
   "license": "Apache-2.0",

package/src/index.js

@@ -364,6 +364,21 @@ export default class Workbench {
         id: node.id
       };
 
+      // Config-only nodes (remote-mcp-tool) have no process function —
+      // they exist for the plugin loop, not direct execution. If one
+      // lands in the queue anyway (e.g. a dangling MCP node with no
+      // plugin link), no-op instead of crashing the whole run.
+      if (typeof nodeDefinition.process !== 'function') {
+        this.logDebug(`Node [${node.id}] (${node.type}) is config-only; skipping direct execution.`);
+        const endDate = new Date();
+        timelineEntry.outputs = {};
+        timelineEntry.endTime = endDate.toISOString();
+        timelineEntry.durationMs = endDate - startDate;
+        timelineEntry.status = 'success';
+        this.timeline.push(timelineEntry);
+        return {};
+      }
+
       const outputs = await this._raceAbort(
         nodeDefinition.process({inputs, settings, config: this.config, nodeConfig})
       );
@@ -1077,7 +1092,21 @@ export default class Workbench {
         await this.config.integrations.sqlite.disconnect();
         delete this.config.integrations.sqlite;
       }
-      
+
+      // Clean up node-level knowledge base integrations (keyed knowledgeBase:<uuid>).
+      if (this.config.integrations) {
+        for (const key of Object.keys(this.config.integrations)) {
+          if (!key.startsWith('knowledgeBase:')) continue;
+          this.logDebug(`Cleaning up node-level knowledge base integration ${key}...`);
+          try {
+            await this.config.integrations[key].disconnect();
+          } catch (err) {
+            this.logDebug(`Failed to disconnect ${key}: ${err.message}`);
+          }
+          delete this.config.integrations[key];
+        }
+      }
+
       // Clean up any imported engines that were created
       // These are stored in the cache when import nodes are processed
       const rawStore = this.cache.getRawStore();
@@ -2337,10 +2366,13 @@ export default class Workbench {
             }
           }
         }
-        // Prepare the tool call message for the next LLM call
+        // Prepare the tool call message for the next LLM call.
+        // Preserve any text the model emitted alongside the tool calls —
+        // nulling it here loses it from both the next round's context and
+        // the final conversation output.
         toolCallMessage = {
           role: "assistant",
-          content: null,
+          content: llmResult.content ?? null,
           tool_calls: llmResult.tool_calls
         };
         toolCallCount++;
@@ -2464,6 +2496,15 @@ export default class Workbench {
    * @returns {boolean} True if the node is a plugin or macro
    */
   isLocalNodePlugin(node) {
+    // Remote MCP tool nodes and manual tool nodes carry is_plugin —
+    // the flag drives shared plugin BEHAVIOR (entry-node exclusion,
+    // propagation skip, the canvas's plugin drag-and-dock UX) — but
+    // neither is a LOCAL plugin: MCP tools load their schemas from
+    // the remote server (isRemoteMCPTool branch) and manual tools
+    // are caller-executed pass-throughs (isManualToolNode branch).
+    // Classifying either as local would misroute them in the plugin
+    // loop (bogus single-tool schema / unwanted process execution).
+    if (isRemoteMCPTool(node) || isManualToolNode(node)) return false;
     const thisNodeConfig = this.nodes[node.type]?.config || {};
     return thisNodeConfig.is_plugin || thisNodeConfig.is_macro;
   }
@@ -2879,21 +2920,44 @@ export default class Workbench {
    * @private
    */
   _trackKnowledgeFiles() {
-    // Track main flow's knowledge base file
-    if (this.flow.knowledgeDbPath) {
-      this.trackKnowledgeFile(this.flow.knowledgeDbPath);
-    }
+    // Host-provided knowledge db paths are HOST-OWNED: the engine must
+    // never delete them unless the host explicitly opts in (hosted
+    // runners that hand the engine per-run temp copies set
+    // config.knowledgeBase.cleanupDbFiles = true). The engine's own
+    // archive extractions live under ./.temp and are always cleaned.
+    const optIn = this.config?.knowledgeBase?.cleanupDbFiles === true;
+    const track = (filePath) => {
+      if (!filePath) return;
+      if (optIn || this._isEngineTempPath(filePath)) {
+        this.trackKnowledgeFile(filePath);
+      }
+    };
+
+    track(this.flow.knowledgeDbPath);
 
-    // Track import knowledge base files
     if (this.flow.imports && Array.isArray(this.flow.imports)) {
       for (const importDef of this.flow.imports) {
-        if (importDef.knowledgeDbPath) {
-          this.trackKnowledgeFile(importDef.knowledgeDbPath);
-        }
+        track(importDef.knowledgeDbPath);
+      }
+    }
+
+    if (this.flow.knowledgeDbPaths && typeof this.flow.knowledgeDbPaths === 'object') {
+      for (const dbPath of Object.values(this.flow.knowledgeDbPaths)) {
+        track(dbPath);
       }
     }
   }
 
+  /** Paths inside the engine's own ./.temp extraction dir. @private */
+  _isEngineTempPath(filePath) {
+    try {
+      const tempDir = path.resolve(process.cwd(), '.temp') + path.sep;
+      return path.resolve(filePath).startsWith(tempDir);
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Clean up temporary knowledge base files for this specific engine instance
    * @private
@@ -2996,3 +3060,9 @@ export default class Workbench {
     }
   }
 }
+
+// Base class for bring-your-own knowledge bases: implement its methods
+// over your own store (SQL database, vector store, HTTP service) and
+// pass an instance via `config.knowledgeBase.instance` (flow-global)
+// or `config.knowledgeBase.instances[kbUuid]` (per Knowledge Base node).
+export { KnowledgeBaseInterface } from './integrations/knowledge-base-interface.js';

package/src/integrations/firecrawl.js

@@ -82,6 +82,77 @@ export default class FirecrawlIntegration {
         }
     }
 
+    /**
+     * Search the web with the Firecrawl Search API
+     * @param {Object} params - Search parameters (query, limit, ...)
+     * @returns {Promise<Object>} Search response
+     */
+    async search(params = {}) {
+        try {
+            const url = `${this.options.baseURL}/search`;
+
+            // Remove any params that are null, undefined, or empty strings
+            Object.keys(params).forEach(key => {
+                if (params[key] === '') {
+                    delete params[key];
+                }
+                if (params[key] === null) {
+                    delete params[key];
+                }
+                if (params[key] === undefined) {
+                    delete params[key];
+                }
+                if (Array.isArray(params[key]) && params[key].length === 0) {
+                    delete params[key];
+                }
+            });
+
+            const requestHeaders = { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.apiKey}` };
+            const startTime = Date.now();
+
+            const response = await axios({
+                url: url,
+                method: 'POST',
+                headers: requestHeaders,
+                data: params,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'firecrawl', nodeId: null, nodeType: null,
+                request: { method: 'POST', url, headers: requestHeaders, body: params },
+                response: { status: response.status, statusText: response.statusText },
+                duration: Date.now() - startTime, error: null
+            });
+
+            if (response.status >= 400) {
+                throw new Error(`Firecrawl API error: ${response.status} - ${response.data?.error || response.statusText}`);
+            }
+
+            return response.data;
+
+        } catch (error) {
+            // Note: emitAPICallEvent for error case is handled by the catch in the caller
+            // since errors from axios.post throw before we can capture the response
+            if (error.response) {
+                const status = error.response.status;
+                const statusText = error.response.statusText;
+                const responseData = error.response.data;
+
+                let errorMessage = `Firecrawl API Error (${status} ${statusText})`;
+                if (responseData?.error) {
+                    errorMessage += `: ${responseData.error}`;
+                }
+
+                throw new Error(errorMessage);
+            } else if (error.request) {
+                throw new Error('Firecrawl API Error: No response received');
+            } else {
+                throw new Error(`Firecrawl API Error: ${error.message}`);
+            }
+        }
+    }
+
     /**
      * Helper function to convert comma-separated string to array
      * @param {string|Array} input - String or array input

package/src/integrations/knowledge-base-interface.js

@@ -116,4 +116,53 @@ export class KnowledgeBaseInterface {
   async disconnect() {
     throw new Error('disconnect() method must be implemented by knowledge base integration');
   }
+
+  /**
+   * Keyword (exact-match) search over chunk content.
+   * @param {string} query @param {Object} options - { limit, document_id }
+   * @returns {Promise<Array>} chunk-shaped rows
+   */
+  async keywordSearch(query, options = {}) {
+    throw new Error('keywordSearch() method must be implemented by knowledge base integration');
+  }
+
+  /** List documents. @param {Object} options - { limit, offset } */
+  async listDocuments(options = {}) {
+    throw new Error('listDocuments() method must be implemented by knowledge base integration');
+  }
+
+  /** Page one document's chunks. @param {Object} options - { startIndex, limit } */
+  async getChunks(documentId, options = {}) {
+    throw new Error('getChunks() method must be implemented by knowledge base integration');
+  }
+
+  /** One chunk plus its neighbors. @param {Object} options - { before, after } */
+  async getChunkWindow(documentId, chunkIndex, options = {}) {
+    throw new Error('getChunkWindow() method must be implemented by knowledge base integration');
+  }
+
+  /** Tabular registry: table schemas + sample rows. @param {Object} options - { sampleLimit } */
+  async listTables(options = {}) {
+    throw new Error('listTables() method must be implemented by knowledge base integration');
+  }
+
+  /** Graph: entities, most-connected first. @param {Object} options - { limit, offset, type, search } */
+  async listEntities(options = {}) {
+    throw new Error('listEntities() method must be implemented by knowledge base integration');
+  }
+
+  /** Graph: resolve an entity by id or case-insensitive name. */
+  async getEntity(ref) {
+    throw new Error('getEntity() method must be implemented by knowledge base integration');
+  }
+
+  /** Graph: relations touching an entity. @param {Object} options - { direction, relation_type, limit } */
+  async getNeighbors(entityRef, options = {}) {
+    throw new Error('getNeighbors() method must be implemented by knowledge base integration');
+  }
+
+  /** Graph: shortest relation chain between two entities. @param {Object} options - { max_depth } */
+  async findPath(fromRef, toRef, options = {}) {
+    throw new Error('findPath() method must be implemented by knowledge base integration');
+  }
 }