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

package/nodes/knowledge-base/knowledge-base.config.json

@@ -0,0 +1,32 @@
+{
+  "display_name": "Knowledge Base",
+  "tagline": "Reference a knowledge base",
+  "description": "References a workspace knowledge base by id and emits a handle to it. Wire this node's output into a Semantic Search (or Query Knowledge Base) node to search that KB. Attach one Knowledge Base node to several search nodes to reuse the same KB — like importing a subflow, the KB is one thing they all depend on.",
+  "icon": "database",
+  "category": "knowledge",
+  "is_constant": true,
+  "is_plugin": false,
+  "is_output": false,
+  "custom_render_height": 76,
+  "inputs": [],
+  "outputs": [
+    {
+      "name": "knowledge_base",
+      "primary": true,
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "A reference (handle) to the selected knowledge base."
+    }
+  ],
+  "settings": [
+    {
+      "name": "uuid",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base_ref",
+      "description": "The knowledge base this node references.",
+      "default": null
+    }
+  ],
+  "timeout": 3000,
+  "retry_limit": 1
+}

package/nodes/knowledge-base/knowledge-base.process.js

@@ -0,0 +1,15 @@
+export default async ({ inputs, settings, config }) => {
+  // A pure reference/source node: it carries a KB id in its settings and emits
+  // it as a `knowledge_base` handle. The runtime KB itself (the `.db`) is
+  // resolved host-side (ZeroWidth's flow-runner pulls each referenced KB and
+  // hands the engine an integration keyed by this uuid) — this node only names
+  // which one. Consumers (semantic-search) read the uuid off the handle and
+  // look up config.integrations.knowledgeBases[uuid].
+  const uuid = settings?.uuid ?? null;
+  if (!uuid) {
+    return { knowledge_base: null };
+  }
+  const handle = { uuid };
+  if (settings?.name) handle.name = settings.name;
+  return { knowledge_base: handle };
+};

package/nodes/list-documents/list-documents.config.json

@@ -0,0 +1,60 @@
+{
+  "display_name": "List Documents",
+  "tagline": "List everything in a KB",
+  "description": "List the documents in a knowledge base (id, name, type, size, chunk count) — for browsing or letting an agent pick a document to read. Wire a Knowledge Base node into knowledge_base, same as the search nodes.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": true,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to list, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "limit",
+      "display_name": "Limit",
+      "type": "number",
+      "description": "Maximum number of documents to return",
+      "default": 100
+    },
+    {
+      "name": "offset",
+      "display_name": "Offset",
+      "type": "number",
+      "description": "Number of documents to skip (pagination)",
+      "default": 0
+    }
+  ],
+  "outputs": [
+    {
+      "name": "documents",
+      "display_name": "Documents",
+      "type": "array",
+      "description": "Document rows (id, display_name, file_type, file_size, chunk_count, …)"
+    },
+    {
+      "name": "count",
+      "display_name": "Count",
+      "type": "number",
+      "description": "Number of documents returned"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the listing completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed"
+    }
+  ],
+  "settings": []
+}

package/nodes/list-documents/list-documents.process.js

@@ -0,0 +1,25 @@
+export default async ({ inputs, config }) => {
+    try {
+        // Shared KB wiring (see semantic-search / keyword-search): a
+        // knowledge_base handle names a KB by uuid, falling back to the
+        // flow-global KB. See ADR 0023.
+        const kbRef = inputs.knowledge_base;
+        const knowledgeBase =
+            (kbRef && kbRef.uuid
+                ? config.integrations?.[`knowledgeBase:${kbRef.uuid}`]
+                : null) ||
+            config.integrations?.knowledgeBase ||
+            config.integrations?.sqlite;
+
+        if (!knowledgeBase) {
+            throw new Error("Knowledge base integration not found. Make sure a knowledge database is available.");
+        }
+
+        const { limit = 100, offset = 0 } = inputs;
+        const documents = await knowledgeBase.listDocuments({ limit, offset });
+
+        return { documents, count: documents.length, success: true, error: null };
+    } catch (error) {
+        return { documents: [], count: 0, success: false, error: error.message };
+    }
+};

package/nodes/list-entities/list-entities.config.json

@@ -0,0 +1,74 @@
+{
+  "display_name": "List Entities",
+  "tagline": "Browse a knowledge graph",
+  "description": "List the entities in a Graph knowledge base, highest-degree (most-connected) first — for browsing the graph or letting an agent discover what it can traverse. Optionally filter by entity type or a name substring. Wire a Knowledge Base node into knowledge_base, same as the search nodes.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": true,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to list, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "type",
+      "display_name": "Entity Type",
+      "type": "string",
+      "description": "Optional: only entities of this type (e.g. person, organization). Case-insensitive.",
+      "default": null
+    },
+    {
+      "name": "search",
+      "display_name": "Name Search",
+      "type": "string",
+      "description": "Optional: only entities whose name contains this text (case-insensitive).",
+      "default": null
+    },
+    {
+      "name": "limit",
+      "display_name": "Limit",
+      "type": "number",
+      "description": "Maximum number of entities to return",
+      "default": 100
+    },
+    {
+      "name": "offset",
+      "display_name": "Offset",
+      "type": "number",
+      "description": "Number of entities to skip (pagination)",
+      "default": 0
+    }
+  ],
+  "outputs": [
+    {
+      "name": "entities",
+      "display_name": "Entities",
+      "type": "array",
+      "description": "Entity rows (id, name, type, description, degree, …), most-connected first"
+    },
+    {
+      "name": "count",
+      "display_name": "Count",
+      "type": "number",
+      "description": "Number of entities returned"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the listing completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed"
+    }
+  ],
+  "settings": []
+}

package/nodes/list-entities/list-entities.process.js

@@ -0,0 +1,25 @@
+export default async ({ inputs, config }) => {
+    try {
+        // Shared KB wiring (see semantic-search / keyword-search): a
+        // knowledge_base handle names a KB by uuid, falling back to the
+        // flow-global KB. See ADR 0023.
+        const kbRef = inputs.knowledge_base;
+        const knowledgeBase =
+            (kbRef && kbRef.uuid
+                ? config.integrations?.[`knowledgeBase:${kbRef.uuid}`]
+                : null) ||
+            config.integrations?.knowledgeBase ||
+            config.integrations?.sqlite;
+
+        if (!knowledgeBase) {
+            throw new Error("Knowledge base integration not found. Make sure a knowledge database is available.");
+        }
+
+        const { limit = 100, offset = 0, type = null, search = null } = inputs;
+        const entities = await knowledgeBase.listEntities({ limit, offset, type, search });
+
+        return { entities, count: entities.length, success: true, error: null };
+    } catch (error) {
+        return { entities: [], count: 0, success: false, error: error.message };
+    }
+};

package/nodes/query-knowledge-base/query-knowledge-base.config.json

@@ -14,6 +14,14 @@
       "description": "SQL query to execute against the knowledge database",
       "required": true
     },
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to query, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
     {
       "name": "params",
       "display_name": "Parameters",
@@ -49,6 +57,12 @@
       "type": "number",
       "description": "Number of rows affected or returned"
     },
+    {
+      "name": "truncated",
+      "display_name": "Truncated",
+      "type": "boolean",
+      "description": "True when the returned data was capped (>1000 rows) — add a LIMIT to the query for the full set"
+    },
     {
       "name": "operation",
       "display_name": "Operation",
@@ -63,13 +77,6 @@
     }
   ],
   "settings": [
-    {
-      "name": "database_path",
-      "display_name": "Database Path",
-      "type": "string",
-      "description": "Path to the knowledge database file (relative to orchestration)",
-      "default": "knowledge.db"
-    },
     {
       "name": "timeout",
       "display_name": "Query Timeout",

package/nodes/query-knowledge-base/query-knowledge-base.process.js

@@ -1,12 +1,20 @@
-export default async ({inputs, settings, config, nodeConfig}) => {
-   // Get knowledge base integration from engine (supports multiple backends)
-   const knowledgeBase = config.integrations?.knowledgeBase || config.integrations?.sqlite;
+export default async ({inputs, config}) => {
+   // Resolve which knowledge base to query — SAME wiring as semantic-search
+   // and keyword-search: a `knowledge_base` handle wired in from a Knowledge
+   // Base node names a specific KB by uuid (resolved to a per-KB integration
+   // keyed knowledgeBase:<uuid>), falling back to the flow-global KB. See ADR 0023.
+   const kbRef = inputs.knowledge_base;
+   const knowledgeBase =
+       (kbRef && kbRef.uuid
+           ? config.integrations?.[`knowledgeBase:${kbRef.uuid}`]
+           : null) ||
+       config.integrations?.knowledgeBase ||
+       config.integrations?.sqlite;
    if (!knowledgeBase) {
        throw new Error("Knowledge base integration not found. Make sure a knowledge database is available.");
    }
 
     const { query, params = [], operation = 'SELECT' } = inputs;
-    const { database_path = 'knowledge.db', timeout = 5000 } = settings;
 
     if (!query || typeof query !== 'string') {
         throw new Error("Query is required and must be a string");
@@ -25,11 +33,23 @@ export default async ({inputs, settings, config, nodeConfig}) => {
     // Execute the query
     const result = await knowledgeBase.query(query, params, operation);
 
+    // Cap the rows returned into the flow so a broad SELECT can't bloat the run
+    // payload. rowCount stays the true count; `truncated` flags the cut (never
+    // silently). Bump the SQL's own LIMIT for fewer/more rows.
+    const MAX_ROWS = 1000;
+    let data = result.data;
+    let truncated = false;
+    if (Array.isArray(data) && data.length > MAX_ROWS) {
+        data = data.slice(0, MAX_ROWS);
+        truncated = true;
+    }
+
     return {
-        data: result.data,
+        data,
         success: result.success,
         rowCount: result.rowCount,
         operation: result.operation,
+        truncated,
         error: null
     };
 };

package/nodes/read-chunks/read-chunks.config.json

@@ -0,0 +1,79 @@
+{
+  "display_name": "Read Chunks",
+  "tagline": "Paginate through a document",
+  "description": "Read a document's chunks in order starting at a chunk index — paginate through a document, or read what came AFTER a chunk you found via search (set start_index to that chunk's index + 1). Feed next_index back in to page forward.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": true,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "document_id",
+      "display_name": "Document ID",
+      "type": "string",
+      "description": "The document to read chunks from",
+      "required": true
+    },
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "start_index",
+      "display_name": "Start Index",
+      "type": "number",
+      "description": "First chunk index to read (0-based). To continue after a found chunk, use its index + 1.",
+      "default": 0
+    },
+    {
+      "name": "limit",
+      "display_name": "Limit",
+      "type": "number",
+      "description": "Maximum number of chunks to return",
+      "default": 10
+    }
+  ],
+  "outputs": [
+    {
+      "name": "chunks",
+      "display_name": "Chunks",
+      "type": "array",
+      "description": "Chunks with index >= start_index, ascending"
+    },
+    {
+      "name": "count",
+      "display_name": "Count",
+      "type": "number",
+      "description": "Number of chunks returned"
+    },
+    {
+      "name": "next_index",
+      "display_name": "Next Index",
+      "type": "number",
+      "description": "start_index for the next page, or null if there are no more chunks"
+    },
+    {
+      "name": "has_more",
+      "display_name": "Has More",
+      "type": "boolean",
+      "description": "Whether more chunks remain after this page"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the read completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed"
+    }
+  ],
+  "settings": []
+}

package/nodes/read-chunks/read-chunks.process.js

@@ -0,0 +1,49 @@
+export default async ({ inputs, config }) => {
+    try {
+        // Shared KB wiring (see semantic-search / keyword-search). ADR 0023.
+        const kbRef = inputs.knowledge_base;
+        const knowledgeBase =
+            (kbRef && kbRef.uuid
+                ? config.integrations?.[`knowledgeBase:${kbRef.uuid}`]
+                : null) ||
+            config.integrations?.knowledgeBase ||
+            config.integrations?.sqlite;
+
+        if (!knowledgeBase) {
+            throw new Error("Knowledge base integration not found. Make sure a knowledge database is available.");
+        }
+
+        const { document_id, start_index = 0, limit = 10 } = inputs;
+        if (!document_id || typeof document_id !== 'string') {
+            throw new Error("document_id is required and must be a string");
+        }
+
+        // Fetch one extra to detect whether more chunks remain after this page.
+        const fetched = await knowledgeBase.getChunks(document_id, {
+            startIndex: start_index,
+            limit: limit + 1,
+        });
+        const hasMore = fetched.length > limit;
+        const chunks = hasMore ? fetched.slice(0, limit) : fetched;
+        const last = chunks[chunks.length - 1];
+        const nextIndex = hasMore && last ? last.chunk_index + 1 : null;
+
+        return {
+            chunks,
+            count: chunks.length,
+            next_index: nextIndex,
+            has_more: hasMore,
+            success: true,
+            error: null,
+        };
+    } catch (error) {
+        return {
+            chunks: [],
+            count: 0,
+            next_index: null,
+            has_more: false,
+            success: false,
+            error: error.message,
+        };
+    }
+};

package/nodes/remote-mcp-tool/remote-mcp-tool.config.json

@@ -5,6 +5,7 @@
   "icon": "fa-plug",
   "category": "tools",
   "is_constant": true,
+  "is_plugin": true,
   "inputs": [],
   "outputs": [],
   "settings": [

package/nodes/semantic-search/semantic-search.config.json

@@ -6,7 +6,7 @@
   "is_constant": false,
   "is_plugin": true,
   "is_output": false,
-  "needs_key_from": ["openai"],
+  "needs_key_from": ["openrouter"],
   "inputs": [
     {
       "name": "query",
@@ -15,6 +15,14 @@
       "description": "Text query to search for semantically similar content",
       "required": true
     },
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to search, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
     {
       "name": "limit",
       "display_name": "Result Limit",

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.0.0",
   "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",