@zerowidth/workbench-sdk 2.0.0 → 2.1.2

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",

package/src/index.js

@@ -20,6 +20,92 @@ import { sanitizeAPICallEvent } from "./utilities/sanitizeAPICall.js";
  * Workbench - Core class for executing node-based flows
  * Handles node loading, input/output validation, and flow execution
  */
+
+/**
+ * The single `role:"tool"` message for one tool result. MCP-style image
+ * content blocks ({type:'image', data, mimeType} with string data) are
+ * replaced in place by a short text note — the pixels are delivered to
+ * the model separately as an ephemeral vision input (see
+ * toolResultToMessages / callLLMWithTools). This same message is used on
+ * the wire, in the accumulated multi-round history, and therefore in the
+ * final conversation output, so all three carry an identical record with
+ * no base64 payload. Image blocks whose data is not a string are left
+ * untouched and stringify as before.
+ */
+function toolResultToDurableMessage(toolResult) {
+  const result = toolResult.result;
+  let durable = result;
+  if (result && Array.isArray(result.content)) {
+    const hasImage = result.content.some(
+      (c) => c && c.type === 'image' && typeof c.data === 'string'
+    );
+    if (hasImage) {
+      durable = {
+        ...result,
+        content: result.content.map((c) =>
+          c && c.type === 'image' && typeof c.data === 'string'
+            ? {
+                type: 'text',
+                text: `[image (${c.mimeType || 'image/png'}) — delivered to the model as a vision input]`,
+              }
+            : c
+        ),
+      };
+    }
+  }
+  return {
+    role: 'tool',
+    tool_call_id: toolResult.tool_call_id,
+    name: toolResult.name,
+    content: typeof durable === 'string' ? durable : JSON.stringify(durable),
+  };
+}
+
+/**
+ * Split one tool result into the wire messages for the next LLM round:
+ * the durable `role:"tool"` message plus, when the result carries image
+ * content blocks, an ephemeral `role:"user"` vision message with
+ * `image_url` data-URI parts. An OpenAI-style tool message is text-only —
+ * stringifying image blocks hands the model base64 soup and it
+ * confabulates what the image "probably" shows.
+ *
+ * The caller must insert vision messages ABOVE the entire trailing run of
+ * tool-cycle messages, not adjacent to this round's cycle: LLM nodes
+ * rebuild their `conversation` output by walking the wire messages
+ * backwards and stopping at the first message that is neither a tool
+ * result nor an assistant tool_calls turn. Placed above the whole run,
+ * a vision message is naturally excluded from the durable output while
+ * every tool cycle below it survives the walk.
+ */
+function toolResultToMessages(toolResult) {
+  const toolMessage = toolResultToDurableMessage(toolResult);
+  const result = toolResult.result;
+  let visionMessage = null;
+  if (result && Array.isArray(result.content)) {
+    const images = result.content.filter(
+      (c) => c && c.type === 'image' && typeof c.data === 'string'
+    );
+    if (images.length > 0) {
+      visionMessage = {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: `[Image${images.length > 1 ? 's' : ''} returned by the ${toolResult.name} tool call (${toolResult.tool_call_id}) — this is the actual content:]`,
+          },
+          ...images.map((img) => ({
+            type: 'image_url',
+            image_url: {
+              url: `data:${img.mimeType || 'image/png'};base64,${img.data}`,
+            },
+          })),
+        ],
+      };
+    }
+  }
+  return { toolMessage, visionMessage };
+}
+
 export default class Workbench {
 
 
@@ -2171,14 +2257,7 @@ export default class Workbench {
       if (toolCallMessage && tool_results.length > 0) {
         accumulatedMessages = [...accumulatedMessages, toolCallMessage];
         for (const toolResult of tool_results) {
-          accumulatedMessages.push({
-            role: "tool",
-            tool_call_id: toolResult.tool_call_id,
-            name: toolResult.name,
-            content: typeof toolResult.result === "string"
-              ? toolResult.result
-              : JSON.stringify(toolResult.result)
-          });
+          accumulatedMessages.push(toolResultToDurableMessage(toolResult));
         }
       }
 
@@ -2366,10 +2445,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++;
@@ -2848,27 +2930,34 @@ export default class Workbench {
 
     // If this is a tool call response, append it to the messages array (OpenAI style)
     if (toolCallMessage && toolResults && Array.isArray(llmInputs.messages)) {
-
-      // 
-      llmInputs.messages = [
-        ...llmInputs.messages,
-        toolCallMessage
-      ];
-
-      for(const toolResult of toolResults) {
+      const toolMessages = [];
+      const visionMessages = [];
+      for (const toolResult of toolResults) {
         // You may need to adapt this for other LLMs
-          llmInputs.messages = [
-            ...llmInputs.messages,
-            {
-              role: "tool",
-              tool_call_id: toolResult.tool_call_id,
-              name: toolResult.name,
-              content: typeof toolResult.result === "string"
-                ? toolResult.result
-                : JSON.stringify(toolResult.result)
-            }
-          ];
+        const { toolMessage, visionMessage } = toolResultToMessages(toolResult);
+        toolMessages.push(toolMessage);
+        if (visionMessage) visionMessages.push(visionMessage);
+      }
+      // Vision messages go ABOVE the entire trailing tool-cycle run, not
+      // just this round's cycle — a vision message wedged between two
+      // cycles would stop the conversation walk early and cut every
+      // earlier cycle out of the final output (see toolResultToMessages).
+      const base = llmInputs.messages;
+      let insertAt = base.length;
+      while (insertAt > 0) {
+        const m = base[insertAt - 1];
+        const inCycle = m && typeof m === 'object' &&
+          (m.role === 'tool' || (Array.isArray(m.tool_calls) && m.tool_calls.length > 0));
+        if (!inCycle) break;
+        insertAt--;
       }
+      llmInputs.messages = [
+        ...base.slice(0, insertAt),
+        ...visionMessages,
+        ...base.slice(insertAt),
+        toolCallMessage,
+        ...toolMessages
+      ];
     }
 
     // Execute using the shared core logic

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