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

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

@@ -0,0 +1,67 @@
+{
+  "display_name": "Keyword Search",
+  "tagline": "Search by exact words",
+  "description": "Search a knowledge base for chunks containing a word or phrase (case-insensitive substring match). Free and instant — no embeddings. The exact-term complement to Semantic Search; wire a Knowledge Base node into its knowledge_base input the same way.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": true,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "query",
+      "display_name": "Search Text",
+      "type": "string",
+      "description": "Word or phrase to match within chunk 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",
+      "type": "number",
+      "description": "Maximum number of results to return",
+      "default": 10
+    },
+    {
+      "name": "document_id",
+      "display_name": "Document ID Filter",
+      "type": "string",
+      "description": "Optional: restrict results to a specific document uuid.",
+      "default": null
+    }
+  ],
+  "outputs": [
+    {
+      "name": "results",
+      "display_name": "Search Results",
+      "type": "array",
+      "description": "Matching chunks, most matches first"
+    },
+    {
+      "name": "count",
+      "display_name": "Result Count",
+      "type": "number",
+      "description": "Number of results returned"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the search completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if search failed"
+    }
+  ],
+  "settings": []
+}

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

@@ -0,0 +1,45 @@
+export default async ({ inputs, config }) => {
+    try {
+        // Resolve which knowledge base to search — SAME wiring as semantic-search
+        // and query-knowledge-base: 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, limit = 10, document_id = null } = inputs;
+
+        if (!query || typeof query !== 'string') {
+            throw new Error("Query is required and must be a string");
+        }
+
+        // No embeddings — a case-insensitive substring match over chunk content.
+        const results = await knowledgeBase.keywordSearch(query, { limit, document_id });
+
+        return {
+            results: results,
+            count: results.length,
+            success: true,
+            error: null
+        };
+
+    } catch (error) {
+        // Return error information instead of throwing to prevent engine crash
+        return {
+            results: [],
+            count: 0,
+            success: false,
+            error: error.message
+        };
+    }
+};

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/search-internet/search-internet.config.json

@@ -1,10 +1,10 @@
 {
   "display_name": "Search the Internet",
   "tagline": "Search the internet",
-  "description": "Search the web using Google Custom Search - returns clean search results with titles, links, and snippets",
+  "description": "Search the web using Firecrawl Search - returns clean search results with titles, links, and snippets",
   "category": "third-party",
-  "provider": "google",
-  "needs_key_from": ["google_custom_search"],
+  "provider": "firecrawl",
+  "needs_key_from": ["firecrawl"],
   "is_macro": true,
   "is_plugin": true,
   "macro_flow": {
@@ -18,13 +18,13 @@
       },
       {
         "id": "search",
-        "type": "google-custom-search"
+        "type": "firecrawl-search"
       },
       {
         "id": "num_results",
-        "type": "string",
+        "type": "number",
         "settings": {
-          "value": "10"
+          "value": 5
         }
       },
       {
@@ -42,7 +42,7 @@
       },
       {
         "from": { "node_id": "num_results", "port_name": "value" },
-        "to": { "node_id": "search", "port_name": "num" }
+        "to": { "node_id": "search", "port_name": "limit" }
       },
       {
         "from": { "node_id": "search", "port_name": "items" },

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