allow for an AI to write custom tools

Author: monteslu

package-lock.json

@@ -41,7 +41,7 @@
     "pino-pretty": "^13.0.0",
     "prettier": "^3.7.4",
     "prismjs": "^1.30.0",
-    "rawr": "^1.0.0",
+    "rawr": "^1.0.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-simple-code-editor": "^0.14.1",

package.json

@@ -0,0 +1,45 @@
+/**
+ * Tool Out Node - Runtime implementation
+ *
+ * Returns the result of a custom tool execution back to the AI agent.
+ */
+export const toolOutRuntime = {
+  type: 'tool-out',
+
+  onInit() {
+    this.status({ text: 'Ready', fill: 'green' });
+  },
+
+  onInput(msg) {
+    const toolRequest = msg._toolRequest;
+
+    if (!toolRequest || !toolRequest.requestId) {
+      this.status({ text: 'No request', fill: 'yellow' });
+      this.warn('No _toolRequest context found. Wire this node to a tool-in node.');
+      return;
+    }
+
+    const { requestId } = toolRequest;
+    const pending = globalThis._customToolRequests?.get(requestId);
+
+    if (!pending) {
+      this.status({ text: 'Expired', fill: 'yellow' });
+      this.warn(`Request ${requestId} not found or already completed (may have timed out)`);
+      return;
+    }
+
+    // Clear timeout and resolve the promise
+    clearTimeout(pending.timeout);
+    globalThis._customToolRequests.delete(requestId);
+
+    // Return the result
+    pending.resolve(msg.payload);
+
+    this.status({ text: 'Sent', fill: 'green' });
+
+    // Reset status after a moment
+    setTimeout(() => {
+      this.status({ text: 'Ready', fill: 'green' });
+    }, 1000);
+  }
+};

public/workers/mediapipe.worker.js

@@ -0,0 +1,56 @@
+/**
+ * Tool Out Node - Returns result from a custom tool flow
+ */
+export const toolOutNode = {
+  type: 'tool-out',
+  category: 'ai',
+  description: 'Returns the result of a custom tool to the AI',
+  paletteLabel: 'tool out',
+  label: (node) => node.name || 'tool out',
+  color: '#a66bbf',  // Purple for AI nodes
+  fontColor: '#fff',
+  icon: true,
+  faChar: '\uf0ad',  // wrench
+  faColor: 'rgba(255,255,255,0.9)',
+
+  inputs: 1,
+  outputs: 0,
+
+  defaults: {},
+
+  messageInterface: {
+    reads: {
+      payload: {
+        type: 'any',
+        description: 'Result to return to the AI'
+      },
+      _toolRequest: {
+        type: 'object',
+        description: 'Internal: request context from tool-in node'
+      }
+    }
+  },
+
+  renderHelp() {
+    return (
+      <>
+        <p>Returns the result of a custom tool execution back to the AI agent. Must receive a message from a <strong>tool-in</strong> node (which provides the internal request context).</p>
+
+        <h5>Input</h5>
+        <ul>
+          <li><code>msg.payload</code> - The result to return to the AI (any type)</li>
+          <li><code>msg._toolRequest</code> - Internal context from tool-in node (passed through automatically)</li>
+        </ul>
+
+        <h5>Usage</h5>
+        <p>Wire this node at the end of your custom tool flow. The <code>msg.payload</code> will be returned as the tool's result.</p>
+
+        <h5>Example Flow</h5>
+        <pre>{`[tool-in: get_weather]
+    -> [http request: weather API]
+    -> [function: format result]
+    -> [tool-out]`}</pre>
+      </>
+    );
+  }
+};

public/workers/mediapipe.worker.js.map

@@ -0,0 +1,75 @@
+/**
+ * Tool In Node - Runtime implementation
+ *
+ * Registers a custom tool that AI agents can call via MCP.
+ * When called, triggers the flow with the provided arguments.
+ */
+
+// Global registry of custom tools (toolName -> node instance)
+// This is populated by onInit and cleared by onClose
+if (!globalThis._customTools) {
+  globalThis._customTools = new Map();
+}
+
+// Pending tool requests waiting for responses (requestId -> { resolve, reject, timeout })
+if (!globalThis._customToolRequests) {
+  globalThis._customToolRequests = new Map();
+}
+
+export const toolInRuntime = {
+  type: 'tool-in',
+
+  onInit() {
+    const toolName = this.config.toolName;
+
+    if (!toolName) {
+      this.status({ text: 'No name', fill: 'red' });
+      this.error('Tool name is required');
+      return;
+    }
+
+    // Validate tool name (no spaces, alphanumeric + underscore)
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(toolName)) {
+      this.status({ text: 'Invalid name', fill: 'red' });
+      this.error('Tool name must start with a letter or underscore and contain only letters, numbers, and underscores');
+      return;
+    }
+
+    // Check for duplicate tool names
+    if (globalThis._customTools.has(toolName)) {
+      this.status({ text: 'Duplicate', fill: 'yellow' });
+      this.warn(`Tool "${toolName}" is already defined by another node`);
+    }
+
+    // Register this tool
+    globalThis._customTools.set(toolName, {
+      nodeId: this.id,
+      toolName,
+      description: this.config.description || '',
+      node: this
+    });
+
+    this.status({ text: toolName, fill: 'green' });
+  },
+
+  // Called by MCP handler when AI invokes this tool
+  invoke(message, requestId) {
+    // Merge incoming message with _toolRequest context
+    const msg = {
+      ...(message || {}),
+      _toolRequest: {
+        requestId,
+        toolName: this.config.toolName,
+        nodeId: this.id
+      }
+    };
+    this.send(msg);
+  },
+
+  onClose() {
+    const toolName = this.config.toolName;
+    if (toolName && globalThis._customTools.get(toolName)?.nodeId === this.id) {
+      globalThis._customTools.delete(toolName);
+    }
+  }
+};

src/nodes/ai/custom-out.js

@@ -0,0 +1,77 @@
+/**
+ * Tool In Node - Defines an AI-callable tool backed by a flow
+ */
+export const toolInNode = {
+  type: 'tool-in',
+  category: 'ai',
+  description: 'Defines a custom tool and receives calls to it from an AI agent',
+  paletteLabel: 'tool in',
+  label: (node) => node.name || node.toolName || 'tool in',
+  color: '#a66bbf',  // Purple for AI nodes
+  fontColor: '#fff',
+  icon: true,
+  faChar: '\uf0ad',  // wrench
+  faColor: 'rgba(255,255,255,0.9)',
+
+  inputs: 0,
+  outputs: 1,
+
+  defaults: {
+    toolName: {
+      type: 'string',
+      default: '',
+      label: 'Tool Name',
+      placeholder: 'get_weather',
+      required: true,
+      description: 'Name for the tool (no spaces, like a function name)'
+    },
+    description: {
+      type: 'string',
+      default: '',
+      label: 'Description',
+      placeholder: 'Gets the current weather for a location',
+      description: 'Description of what this tool does (helps AI know when to use it)'
+    }
+  },
+
+  messageInterface: {
+    writes: {
+      payload: {
+        type: 'any',
+        description: 'Payload from the message passed by the AI'
+      },
+      topic: {
+        type: 'string',
+        description: 'Topic from the message (if provided)'
+      },
+      _toolRequest: {
+        type: 'object',
+        description: 'Internal: request context for tool-out node'
+      }
+    }
+  },
+
+  renderHelp() {
+    return (
+      <>
+        <p>Defines a custom tool that AI agents can call via MCP. When an AI calls this tool, the flow is triggered with the provided arguments in <code>msg.payload</code>.</p>
+
+        <h5>Configuration</h5>
+        <ul>
+          <li><strong>Tool Name</strong> - Unique name for the tool (no spaces). This is how the AI will call it.</li>
+          <li><strong>Description</strong> - Explains what the tool does. Good descriptions help the AI know when to use it.</li>
+        </ul>
+
+        <h5>Output</h5>
+        <ul>
+          <li><code>msg.payload</code> - The payload from the message passed by the AI</li>
+          <li><code>msg.topic</code> - Optional topic from the message</li>
+          <li><code>msg._toolRequest</code> - Internal context (pass through to tool-out)</li>
+        </ul>
+
+        <h5>Usage</h5>
+        <p>Wire this node through your flow logic, then end with a <strong>tool-out</strong> node to return the result to the AI.</p>
+      </>
+    );
+  }
+};

src/nodes/ai/custom-out.jsx

@@ -112,6 +112,8 @@ import { imageAiConfigNode, imageAiNode } from './ai/image-ai.jsx';
 import { llmConfigNode, llmNode } from './ai/llm.jsx';
 import { mcpOutputNode } from './ai/mcp-output.jsx';
 import { mcpInputNode } from './ai/mcp-input.jsx';
+import { toolInNode } from './ai/custom-tool.jsx';
+import { toolOutNode } from './ai/custom-out.jsx';
 
 // Output nodes
 import { canvasConfigNode, canvasNode } from './output/canvas.jsx';
@@ -224,6 +226,8 @@ import { audioStemsNode } from './audio/stems.jsx';
   llmNode,
   mcpOutputNode,
   mcpInputNode,
+  toolInNode,
+  toolOutNode,
 
   // Output
   canvasNode,

src/nodes/ai/custom-tool.js

@@ -86,6 +86,8 @@ import { imageAiConfigRuntime, imageAiRuntime } from './ai/image-ai.js';
 import { llmConfigRuntime, llmRuntime } from './ai/llm.js';
 import { mcpOutputRuntime } from './ai/mcp-output.js';
 import { mcpInputRuntime } from './ai/mcp-input.js';
+import { toolInRuntime } from './ai/custom-tool.js';
+import { toolOutRuntime } from './ai/custom-out.js';
 
 // Output nodes
 import { canvasConfigRuntime, canvasRuntime } from './output/canvas.js';
@@ -197,6 +199,8 @@ import { audioStemsRuntime } from './audio/stems.js';
   llmRuntime,
   mcpOutputRuntime,
   mcpInputRuntime,
+  toolInRuntime,
+  toolOutRuntime,
 
   // Output
   canvasRuntime,