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

package/nodes/combine-document-chunks/combine-document-chunks.config.json

@@ -25,6 +25,14 @@
       "type": "string",
       "description": "String to use as separator between chunks",
       "default": "\n\n---\n\n"
+    },
+    {
+      "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
     }
   ],
   "outputs": [

package/nodes/combine-document-chunks/combine-document-chunks.process.js

@@ -1,7 +1,14 @@
 export default async ({inputs, settings, config, nodeConfig}) => {
     try {
-        // Get knowledge base integration
-        const knowledgeBase = config.integrations?.knowledgeBase || config.integrations?.sqlite;
+        // Resolve the KB from a knowledge_base handle (shared wiring), 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.");

package/nodes/describe-tables/describe-tables.config.json

@@ -0,0 +1,59 @@
+{
+  "display_name": "Describe Tables",
+  "tagline": "See a KB's tables + columns",
+  "description": "List the tables in a Tabular knowledge base with their columns, types, and row counts — so a model can discover the schema before writing SQL for the Query Knowledge Base node. Wire a Knowledge Base node into knowledge_base, same as the other KB nodes. Returns [] for a docs KB.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": false,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to describe, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "sample_rows",
+      "display_name": "Sample Rows",
+      "type": "number",
+      "description": "Rows to sample per table (0 = none). Samples help an LLM write correct SQL.",
+      "default": 5
+    }
+  ],
+  "outputs": [
+    {
+      "name": "schema",
+      "display_name": "Schema (for LLM)",
+      "type": "string",
+      "description": "Ready-to-paste schema block: CREATE TABLE DDL + a few sample rows (as comments) per table. Feed into an LLM node's context to write SQL."
+    },
+    {
+      "name": "tables",
+      "display_name": "Tables",
+      "type": "array",
+      "description": "[{ table_name, source_name, row_count, columns: [{ name, type }], ddl, sample_rows }]"
+    },
+    {
+      "name": "count",
+      "display_name": "Table Count",
+      "type": "number",
+      "description": "Number of tables"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether it completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed"
+    }
+  ],
+  "settings": []
+}

package/nodes/describe-tables/describe-tables.process.js

@@ -0,0 +1,40 @@
+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 sampleLimit =
+            typeof inputs.sample_rows === "number" ? inputs.sample_rows : 5;
+        const tables = await knowledgeBase.listTables({ sampleLimit });
+
+        // A ready-to-paste schema block for an LLM: CREATE TABLE DDL + a few
+        // sample rows (as comments) per table. Drop `schema` straight into an
+        // LLM node's context to write SQL for the Query Knowledge Base node.
+        const schema = tables
+            .map((t) => {
+                const lines = [t.ddl];
+                if (Array.isArray(t.sample_rows) && t.sample_rows.length > 0) {
+                    lines.push("-- sample rows:");
+                    for (const row of t.sample_rows) {
+                        lines.push("-- " + JSON.stringify(row));
+                    }
+                }
+                return lines.join("\n");
+            })
+            .join("\n\n");
+
+        return { tables, schema, count: tables.length, success: true, error: null };
+    } catch (error) {
+        return { tables: [], schema: "", count: 0, success: false, error: error.message };
+    }
+};

package/nodes/expand-chunk-context/expand-chunk-context.config.json

@@ -0,0 +1,87 @@
+{
+  "display_name": "Expand Chunk Context",
+  "tagline": "Grab chunks around a hit",
+  "description": "Given a chunk (its document_id + chunk_index, e.g. from a search result), return the surrounding chunks — the N before and N after — plus their combined text. The classic RAG move: search finds one chunk, this widens the window so the model has the context around it.",
+  "category": "knowledge",
+  "is_constant": false,
+  "is_plugin": false,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "document_id",
+      "display_name": "Document ID",
+      "type": "string",
+      "description": "The document the anchor chunk belongs to",
+      "required": true
+    },
+    {
+      "name": "chunk_index",
+      "display_name": "Chunk Index",
+      "type": "number",
+      "description": "The anchor chunk's index (e.g. from a search result)",
+      "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": "before",
+      "display_name": "Chunks Before",
+      "type": "number",
+      "description": "How many chunks before the anchor to include",
+      "default": 1
+    },
+    {
+      "name": "after",
+      "display_name": "Chunks After",
+      "type": "number",
+      "description": "How many chunks after the anchor to include",
+      "default": 2
+    },
+    {
+      "name": "separator",
+      "display_name": "Separator",
+      "type": "string",
+      "description": "Joins chunk contents in the combined output",
+      "default": "\n\n"
+    }
+  ],
+  "outputs": [
+    {
+      "name": "chunks",
+      "display_name": "Chunks",
+      "type": "array",
+      "description": "The window of chunks, ascending by index"
+    },
+    {
+      "name": "content",
+      "display_name": "Combined Content",
+      "type": "string",
+      "description": "The window's chunk contents joined by the separator"
+    },
+    {
+      "name": "count",
+      "display_name": "Count",
+      "type": "number",
+      "description": "Number of chunks in the window"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether it completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed"
+    }
+  ],
+  "settings": []
+}

package/nodes/expand-chunk-context/expand-chunk-context.process.js

@@ -0,0 +1,34 @@
+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, chunk_index, before = 1, after = 2, separator = "\n\n" } = inputs;
+        if (!document_id || typeof document_id !== 'string') {
+            throw new Error("document_id is required and must be a string");
+        }
+        if (chunk_index === undefined || chunk_index === null || Number.isNaN(Number(chunk_index))) {
+            throw new Error("chunk_index is required and must be a number");
+        }
+
+        const chunks = await knowledgeBase.getChunkWindow(document_id, Number(chunk_index), {
+            before,
+            after,
+        });
+        const content = chunks.map((c) => c.content ?? '').join(separator);
+
+        return { chunks, content, count: chunks.length, success: true, error: null };
+    } catch (error) {
+        return { chunks: [], content: '', count: 0, success: false, error: error.message };
+    }
+};

package/nodes/find-entity-path/find-entity-path.config.json

@@ -0,0 +1,73 @@
+{
+  "display_name": "Find Entity Path",
+  "tagline": "Connect two graph entities",
+  "description": "Find the shortest chain of relations connecting two entities in a Graph knowledge base (breadth-first, direction-agnostic). Answers \"how are X and Y related?\" with the hop-by-hop path. 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": "from",
+      "display_name": "From Entity",
+      "type": "string",
+      "description": "The starting entity — its name (case-insensitive) or id.",
+      "required": true
+    },
+    {
+      "name": "to",
+      "display_name": "To Entity",
+      "type": "string",
+      "description": "The target entity — its name (case-insensitive) or id.",
+      "required": true
+    },
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to traverse, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "max_depth",
+      "display_name": "Max Depth",
+      "type": "number",
+      "description": "Maximum number of hops to search before giving up.",
+      "default": 4
+    }
+  ],
+  "outputs": [
+    {
+      "name": "found",
+      "display_name": "Found",
+      "type": "boolean",
+      "description": "Whether a path exists within max_depth"
+    },
+    {
+      "name": "hops",
+      "display_name": "Hops",
+      "type": "number",
+      "description": "Number of relations in the path (0 when from = to)"
+    },
+    {
+      "name": "steps",
+      "display_name": "Steps",
+      "type": "array",
+      "description": "The path, node by node: [{ node, via_edge? }] — via_edge names the relation that reached each node"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the search completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed (including unknown entities)"
+    }
+  ],
+  "settings": []
+}

package/nodes/find-entity-path/find-entity-path.process.js

@@ -0,0 +1,51 @@
+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 { from, to, max_depth = 4 } = inputs;
+        if (typeof from !== "string" || from.trim().length === 0) {
+            throw new Error("A from entity name or id is required.");
+        }
+        if (typeof to !== "string" || to.trim().length === 0) {
+            throw new Error("A to entity name or id is required.");
+        }
+
+        const result = await knowledgeBase.findPath(from.trim(), to.trim(), {
+            max_depth,
+        });
+
+        if (!result.from || !result.to) {
+            const missing = !result.from ? from : to;
+            return {
+                found: false,
+                hops: 0,
+                steps: [],
+                success: false,
+                error: `No entity named "${missing}" in this knowledge base. Use List Entities to see what exists.`,
+            };
+        }
+
+        return {
+            found: result.found,
+            hops: result.hops,
+            steps: result.steps,
+            success: true,
+            error: null,
+        };
+    } catch (error) {
+        return { found: false, hops: 0, steps: [], success: false, error: error.message };
+    }
+};

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

@@ -0,0 +1,46 @@
+{
+  "display_name": "Firecrawl Search",
+  "tagline": "Search the web with Firecrawl",
+  "description": "Search the web using the Firecrawl Search API - returns clean search results with titles, links, and snippets",
+  "category": "third-party",
+  "provider": "firecrawl",
+  "needs_key_from": ["firecrawl"],
+  "is_plugin": true,
+  "inputs": [
+    {
+      "name": "query",
+      "display_name": "Search Query",
+      "type": "string",
+      "description": "The search query string",
+      "required": true
+    },
+    {
+      "name": "limit",
+      "display_name": "Number of Results",
+      "type": "number",
+      "description": "Maximum number of search results to return (1-100)",
+      "default": 5
+    }
+  ],
+  "outputs": [
+    {
+      "name": "items",
+      "display_name": "Search Results",
+      "type": "array of objects",
+      "description": "Array of cleaned search result items with title, link, displayLink, snippet, and position"
+    },
+    {
+      "name": "total_results",
+      "display_name": "Total Results",
+      "type": "number",
+      "description": "Number of search results returned"
+    },
+    {
+      "name": "warning",
+      "display_name": "Warning",
+      "type": "string",
+      "description": "Any warning message returned by the Firecrawl API"
+    }
+  ],
+  "settings": []
+}

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

@@ -0,0 +1,54 @@
+export default async ({inputs, settings, config, nodeConfig}) => {
+    // Get Firecrawl integration from engine
+    const firecrawl = config.integrations?.firecrawl;
+    if (!firecrawl) {
+        throw new Error("Firecrawl integration not found");
+    }
+
+    // Build parameters
+    const params = {
+        query: inputs.query
+    };
+
+    // Clamp limit into Firecrawl's accepted 1-100 range
+    if (inputs.limit !== null && inputs.limit !== undefined && inputs.limit !== '') {
+        const limit = Number(inputs.limit);
+        if (!Number.isNaN(limit)) {
+            params.limit = Math.max(1, Math.min(100, Math.floor(limit)));
+        }
+    }
+
+    // Make API request - let errors bubble up to be caught by error manager
+    const response = await firecrawl.search(params);
+
+    // Firecrawl v2 keys results by source ({ web: [...], news: [...], images: [...] });
+    // tolerate a flat array (v1-style envelope) as well.
+    const data = response.data || {};
+    const rawResults = Array.isArray(data) ? data : (data.web || []);
+
+    // Clean up the items to match the shared search-result shape
+    // (title / link / displayLink / snippet) used by search nodes.
+    const items = rawResults.map((result, index) => {
+        let displayLink = null;
+        if (result.url) {
+            try {
+                displayLink = new URL(result.url).hostname;
+            } catch {
+                displayLink = null;
+            }
+        }
+        return {
+            title: result.title || null,
+            link: result.url || null,
+            displayLink: displayLink,
+            snippet: result.description || null,
+            position: result.position !== undefined && result.position !== null ? result.position : index + 1
+        };
+    });
+
+    return {
+        items: items,
+        total_results: items.length,
+        warning: response.warning || null
+    };
+};

package/nodes/firecrawl-search/firecrawl-search.tests.json

@@ -0,0 +1,9 @@
+[
+  {
+    "inputs": {
+      "query": "zerowidth ai"
+    },
+    "expectedError": "Firecrawl integration not found",
+    "description": "Missing integration test - node throws when no firecrawl key is configured"
+  }
+]

package/nodes/get-chunk-by-index/get-chunk-by-index.config.json

@@ -18,6 +18,14 @@
       "type": "number",
       "description": "The index of the chunk to retrieve (0-based)",
       "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
     }
   ],
   "outputs": [

package/nodes/get-chunk-by-index/get-chunk-by-index.process.js

@@ -1,7 +1,14 @@
 export default async ({inputs, settings, config, nodeConfig}) => {
     try {
-        // Get knowledge base integration
-        const knowledgeBase = config.integrations?.knowledgeBase || config.integrations?.sqlite;
+        // Resolve the KB from a knowledge_base handle (shared wiring), 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.");

package/nodes/get-entity-neighbors/get-entity-neighbors.config.json

@@ -0,0 +1,81 @@
+{
+  "display_name": "Get Entity Neighbors",
+  "tagline": "Walk one hop in a graph",
+  "description": "Look up an entity in a Graph knowledge base (by name or id) and return every relation touching it, each with the entity on the far side — one hop of graph traversal. Filter by direction or relation type. 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": "entity",
+      "display_name": "Entity",
+      "type": "string",
+      "description": "The entity to look up — its name (case-insensitive) or id.",
+      "required": true
+    },
+    {
+      "name": "knowledge_base",
+      "display_name": "Knowledge Base",
+      "type": "knowledge_base",
+      "description": "The knowledge base to traverse, from a Knowledge Base node. If omitted, falls back to the flow's default knowledge base.",
+      "required": false,
+      "default": null
+    },
+    {
+      "name": "direction",
+      "display_name": "Direction",
+      "type": "string",
+      "description": "Which relations to include: both, out (entity is the source), or in (entity is the target).",
+      "default": "both",
+      "options": ["both", "out", "in"]
+    },
+    {
+      "name": "relation_type",
+      "display_name": "Relation Type",
+      "type": "string",
+      "description": "Optional: only relations of this type (e.g. works_at). Case-insensitive.",
+      "default": null
+    },
+    {
+      "name": "limit",
+      "display_name": "Limit",
+      "type": "number",
+      "description": "Maximum number of neighbors to return",
+      "default": 50
+    }
+  ],
+  "outputs": [
+    {
+      "name": "entity",
+      "display_name": "Entity",
+      "type": "object",
+      "description": "The resolved entity row (null if not found)"
+    },
+    {
+      "name": "neighbors",
+      "display_name": "Neighbors",
+      "type": "array",
+      "description": "Relations touching the entity: { edge_id, relation_type, description, direction, node }"
+    },
+    {
+      "name": "count",
+      "display_name": "Count",
+      "type": "number",
+      "description": "Number of neighbors returned"
+    },
+    {
+      "name": "success",
+      "display_name": "Success",
+      "type": "boolean",
+      "description": "Whether the lookup completed successfully"
+    },
+    {
+      "name": "error",
+      "display_name": "Error",
+      "type": "string",
+      "description": "Error message if it failed (including entity not found)"
+    }
+  ],
+  "settings": []
+}

package/nodes/get-entity-neighbors/get-entity-neighbors.process.js

@@ -0,0 +1,51 @@
+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 { entity, direction = "both", relation_type = null, limit = 50 } = inputs;
+        if (typeof entity !== "string" || entity.trim().length === 0) {
+            throw new Error("An entity name or id is required.");
+        }
+
+        const result = await knowledgeBase.getNeighbors(entity.trim(), {
+            direction,
+            relation_type,
+            limit,
+        });
+
+        if (!result.entity) {
+            // Soft-fail with a helpful message so an agent can recover by
+            // listing entities instead of dead-ending.
+            return {
+                entity: null,
+                neighbors: [],
+                count: 0,
+                success: false,
+                error: `No entity named "${entity}" in this knowledge base. Use List Entities to see what exists.`,
+            };
+        }
+
+        return {
+            entity: result.entity,
+            neighbors: result.neighbors,
+            count: result.neighbors.length,
+            success: true,
+            error: null,
+        };
+    } catch (error) {
+        return { entity: null, neighbors: [], count: 0, success: false, error: error.message };
+    }
+};