@zerowidth/workbench-sdk 2.1.3 → 2.3.0

package/README.md

@@ -48,7 +48,7 @@ import Workbench from '@zerowidth/workbench-sdk';
 // Create engine instance by passing the location of your configured flow
 const engine = await Workbench.create('./path/to/myflow.zwf', {
   keys: {
-    openrouter: process.env.OPENROUTER_API_KEY
+    inference: process.env.INFERENCE_API_KEY  // your LLM endpoint's key
   }
 });
 
@@ -281,14 +281,36 @@ The engine supports secure API key management for nodes that require external se
 ```javascript
 const engine = await Workbench.create(flow, {
   keys: {
-    openrouter: "sk-...",  // OpenRouter API key
+    inference: "sk-...",  // key for the LLM endpoint (default: OpenRouter)
   }
 });
 ```
 
+### Pointing at your own LLM
+
+Every OpenAI-compatible LLM node runs against a single inference endpoint.
+By default that's OpenRouter, but you can point it at **your own**
+OpenAI-compatible endpoint (vLLM, Ollama, TGI, a LiteLLM proxy, or any
+gateway) — nothing leaves your infrastructure:
+
+```javascript
+const engine = await Workbench.create(flow, {
+  keys: { inference: process.env.MY_LLM_KEY },
+  inferenceBaseURL: "https://llm.my-internal-host/v1",
+});
+```
+
+The model ids in the flow (e.g. `openai/gpt-4o`) must be ones your endpoint
+serves — a LiteLLM `model_list` mapping is the usual way to line these up.
+A custom `inferenceBaseURL` sends plain OpenAI-shaped requests (the
+OpenRouter-only payload fields are dropped automatically).
+
+> **Aliases:** `keys.openrouter` and `openrouterBaseURL` are still accepted
+> as backward-compatible aliases for `keys.inference` and `inferenceBaseURL`.
+
 ### Node Key Requirements
 
-Nodes specify their key requirements in their configuration. All LLMs are configured by default to use OpenRouter, but this can be overridden.
+Nodes specify their key requirements in their configuration. All LLMs are configured by default to use the inference endpoint (OpenRouter unless overridden), but this can be overridden.
 
 ```json
 {

package/nodes/custom-inference/custom-inference.config.json

@@ -0,0 +1,158 @@
+{
+  "display_name": "Custom Inference",
+  "tagline": "Generate text on a bring-your-own endpoint",
+  "description": "Runs a chat completion against a host-registered custom inference provider (an OpenAI-compatible or Azure OpenAI endpoint). The host resolves `settings.provider` to a `custom:<provider>` integration and sends `settings.model` as the model. Used by ZeroWidth's BYO inference endpoints (ADR 0048 Phase 3); the host rewrites a `byo:<provider>:<model>` node into this one at run time.",
+  "category": "llm",
+  "accepts_plugins": true,
+  "settings": [
+    {
+      "name": "provider",
+      "display_name": "Provider",
+      "type": "string",
+      "description": "Name of the host-registered custom inference provider.",
+      "default": null
+    },
+    {
+      "name": "model",
+      "display_name": "Model",
+      "type": "string",
+      "description": "Model / deployment id the endpoint serves.",
+      "default": null
+    }
+  ],
+  "inputs": [
+    {
+      "name": "messages",
+      "display_name": "Conversation",
+      "type": "conversation or message or string",
+      "description": "Array of chat messages that make up the conversation",
+      "required": true
+    },
+    {
+      "name": "system_prompt",
+      "display_name": "System Message",
+      "type": "message or string",
+      "description": "System prompt to instruct the model",
+      "default": null
+    },
+    {
+      "name": "tools",
+      "display_name": "Tools",
+      "type": "tool or array of tools",
+      "description": "Array of tools to use",
+      "default": null,
+      "allow_multiple": true
+    },
+    {
+      "name": "tool_choice",
+      "display_name": "Tool Choice",
+      "type": "string",
+      "description": "Tool selection control",
+      "default": null
+    },
+    {
+      "name": "response_format",
+      "display_name": "Response Format",
+      "type": "object",
+      "description": "Output format specification",
+      "default": null
+    },
+    {
+      "name": "stop",
+      "display_name": "Stop",
+      "type": "string or array",
+      "description": "Custom stop sequences",
+      "default": null
+    },
+    {
+      "name": "temperature",
+      "display_name": "Temperature",
+      "type": "number",
+      "description": "Controls randomness (0-2)",
+      "default": null
+    },
+    {
+      "name": "top_p",
+      "display_name": "Top P",
+      "type": "number",
+      "description": "Controls diversity via nucleus sampling",
+      "default": null
+    },
+    {
+      "name": "max_tokens",
+      "display_name": "Max Tokens",
+      "type": "number",
+      "description": "Maximum tokens to generate",
+      "default": null
+    },
+    {
+      "name": "frequency_penalty",
+      "display_name": "Frequency Penalty",
+      "type": "number",
+      "description": "Reduces repetition (-2 to 2)",
+      "default": null
+    },
+    {
+      "name": "presence_penalty",
+      "display_name": "Presence Penalty",
+      "type": "number",
+      "description": "Encourages new topics (-2 to 2)",
+      "default": null
+    },
+    {
+      "name": "seed",
+      "display_name": "Seed",
+      "type": "number",
+      "description": "Deterministic outputs",
+      "default": null
+    }
+  ],
+  "outputs": [
+    {
+      "name": "conversation",
+      "display_name": "Conversation",
+      "type": "conversation",
+      "can_stream": true,
+      "description": "An array of messages including any tool call & response messages as well as the final generated output."
+    },
+    {
+      "name": "content",
+      "display_name": "Content",
+      "can_stream": true,
+      "type": "string",
+      "description": "The content portion of the final generated response message."
+    },
+    {
+      "name": "message",
+      "display_name": "Final Message",
+      "type": "message",
+      "can_stream": true,
+      "description": "The final generated response message."
+    },
+    {
+      "name": "role",
+      "display_name": "Role",
+      "can_stream": true,
+      "type": "string",
+      "description": "Role of the response (usually 'assistant')"
+    },
+    {
+      "name": "tool_calls",
+      "display_name": "Tool Calls",
+      "type": "array of tools",
+      "description": "Tool calls made by the model"
+    },
+    {
+      "name": "usage",
+      "display_name": "Token Usage",
+      "type": "object",
+      "description": "Token usage statistics"
+    },
+    {
+      "name": "finish_reason",
+      "display_name": "Finish Reason",
+      "type": "string",
+      "description": "Why the completion finished"
+    }
+  ]
+}

package/nodes/custom-inference/custom-inference.process.js

@@ -0,0 +1,117 @@
+export default async ({inputs, settings, config, nodeConfig}) => {
+    try {
+        // Resolve the host-registered custom inference provider (ADR 0048
+        // Phase 3). `settings.provider` names it; the host built a
+        // `custom:<provider>` integration in loadIntegrations from
+        // config.customInferenceProviders. `settings.model` is the model /
+        // Azure deployment the endpoint serves.
+        const providerName = settings?.provider;
+        const model = settings?.model;
+        if (!providerName || !model) {
+            throw new Error("Custom Inference node requires provider + model settings");
+        }
+        const integration = config.integrations?.['custom:' + providerName];
+        if (!integration) {
+            throw new Error(`Custom inference provider "${providerName}" is not configured`);
+        }
+
+        let messages = inputs.messages;
+
+        if(typeof messages === 'string') {
+            messages = [{ role: 'user', content: messages }];
+        }
+
+        if(typeof messages === 'object' && !Array.isArray(messages)) {
+            messages = [messages];
+        }
+
+        if(inputs.system_prompt) {
+            let systemPrompt = inputs.system_prompt;
+            if(typeof systemPrompt === 'string') {
+                systemPrompt = { role: 'system', content: systemPrompt };
+            }
+            messages = [systemPrompt, ...messages];
+        }
+
+        // Build parameters object from the wired inputs (everything but the
+        // conversation itself), mirroring the platform LLM nodes.
+        const params = {};
+        for (const input of (nodeConfig?.inputs || [])) {
+            if (input.name === 'messages') continue;
+            const value = inputs[input.name];
+            if (value !== null && value !== undefined) {
+                if (input.name === 'tools' && Array.isArray(value)) {
+                    params.tools = value.flat();
+                } else {
+                    params[input.name] = value;
+                }
+            }
+        }
+
+        const response = await integration.chatCompletion({
+            model,
+            messages,
+            ...params
+        }, nodeConfig, config);
+
+        // Conversation output: keep only internal-tool history + the fresh
+        // response — identical to the platform chat nodes.
+        const hasInternalToolTracking = config.internal_tool_names !== undefined;
+        const internalToolNames = new Set(config.internal_tool_names || []);
+
+        let conversationMessages = [];
+        if (Array.isArray(messages) && messages.length > 0) {
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const msg = messages[i];
+                if (!msg || typeof msg !== 'object') continue;
+                const isTool = msg.role === 'tool';
+                const hasToolCalls = msg.tool_calls && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0;
+                if (isTool) {
+                    const toolName = msg.name;
+                    if (!hasInternalToolTracking || internalToolNames.has(toolName)) {
+                        conversationMessages.unshift(msg);
+                    }
+                } else if (hasToolCalls) {
+                    const internalCalls = !hasInternalToolTracking
+                        ? msg.tool_calls
+                        : msg.tool_calls.filter(tc => internalToolNames.has(tc.function?.name));
+                    if (internalCalls.length > 0) {
+                        conversationMessages.unshift({ ...msg, tool_calls: internalCalls });
+                    }
+                } else {
+                    break;
+                }
+            }
+        }
+
+        const finalMessage = { content: response.content, role: response.role };
+        if (response.tool_calls && Array.isArray(response.tool_calls) && response.tool_calls.length > 0) {
+            finalMessage.tool_calls = response.tool_calls;
+        }
+        if (response.images) {
+            finalMessage.images = response.images;
+        }
+        conversationMessages.push(finalMessage);
+
+        return {
+            conversation: conversationMessages,
+            message: {
+                content: response.content,
+                role: response.role,
+                tool_calls: response.tool_calls
+            },
+            content: response.content,
+            role: response.role,
+            tool_calls: response.tool_calls,
+            annotations: response.annotations,
+            citations: response.citations,
+            logprobs: response.logprobs,
+            finish_reason: response.finish_reason,
+            usage: response.usage,
+            cost_total: response.cost_total,
+            cost_itemized: response.cost_itemized
+        };
+    } catch (error) {
+        throw new Error(`Custom Inference node error: ${error.message}`);
+    }
+};

package/nodes/json-to-xml/json-to-xml.config.json

@@ -8,8 +8,8 @@
     {
       "name": "json",
       "display_name": "JSON",
-      "type": "object",
-      "description": "The JSON object to convert to XML",
+      "type": "object or array of objects",
+      "description": "The JSON object, or array of objects, to convert to XML",
       "required": true
     },
     {

package/nodes/json-to-yaml/json-to-yaml.config.json

@@ -8,8 +8,8 @@
     {
       "name": "json",
       "display_name": "JSON",
-      "type": "object",
-      "description": "The JSON object to convert to YAML",
+      "type": "object or array of objects",
+      "description": "The JSON object, or array of objects, to convert to YAML",
       "required": true
     },
     {

package/nodes/json-to-yaml/json-to-yaml.tests.json

@@ -97,5 +97,14 @@
     "expected": {
       "yaml": "null"
     }
+  },
+  {
+    "description": "Top-level array of objects",
+    "inputs": {
+      "json": [{"name": "Alice"}, {"name": "Bob"}]
+    },
+    "expected": {
+      "yaml": "- name: Alice\n- name: Bob"
+    }
   }
 ]

package/nodes/message/message.config.json

@@ -23,7 +23,7 @@
     {
       "name": "variables",
       "display_name": "Variables",
-      "type": "object",
+      "type": "object or array of objects",
       "allow_multiple": true,
       "description": "Connect key-value pairs to inject into any matched {{key}} in the text content."
     }

package/nodes/message/message.process.js

@@ -2,6 +2,23 @@
  * Process function for the Message node.
  * Outputs a message object, either from the input or from the settings.
  */
+/**
+ * Render a variable value for injection into message text.
+ * Strings pass through untouched; everything else is JSON encoded so that
+ * nested objects and arrays read as data instead of "[object Object]".
+ */
+const renderVariable = (value) => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    // Circular structures (or anything else JSON can't encode) fall back to
+    // the default coercion rather than failing the whole message.
+    return String(value);
+  }
+};
+
 export default async ({inputs, settings, config}) => {
 
   // If an input value is provided, use it; otherwise use the value from settings
@@ -17,6 +34,12 @@ export default async ({inputs, settings, config}) => {
   if(!inputs.variables) {
     inputs.variables = [];
   }
+
+  // A single connection can deliver an array of key-value objects, so flatten
+  // one level before looking keys up.
+  const variables = (Array.isArray(inputs.variables) ? inputs.variables : [inputs.variables])
+    .flatMap(entry => Array.isArray(entry) ? entry : [entry])
+    .filter(entry => entry !== null && typeof entry === "object");
   
   // if we have variables and text content, we need to replace the text content with the variables
   // do we have a text content item and what index is it
@@ -25,9 +48,9 @@ export default async ({inputs, settings, config}) => {
     message.content[textContentIndex].text = message.content[textContentIndex].text.replace(/\{\{(.*?)\}\}/g, (match, p1) => {
       
       // look for a variable with the key p1
-      let variable = inputs.variables.find(variable => Object.keys(variable).find(key => key === p1));
+      let variable = variables.find(variable => Object.keys(variable).find(key => key === p1));
       if(variable) {
-        return variable[p1];
+        return renderVariable(variable[p1]);
       }
       return match;
     });

package/nodes/message/message.tests.json

@@ -0,0 +1,85 @@
+[
+  {
+    "description": "String variable is injected as-is",
+    "inputs": {
+      "variables": [
+        {
+          "name": "Ada"
+        }
+      ]
+    },
+    "settings": {
+      "role": "user",
+      "content": "Hello {{name}}!"
+    },
+    "expected": {
+      "message": {
+        "role": "user",
+        "content": [
+          {
+            "type": "text",
+            "text": "Hello Ada!"
+          }
+        ]
+      }
+    }
+  },
+  {
+    "description": "Nested object variable is JSON stringified, not [object Object]",
+    "inputs": {
+      "variables": [
+        {
+          "order": {
+            "id": 7,
+            "paid": true
+          }
+        }
+      ]
+    },
+    "settings": {
+      "role": "user",
+      "content": "Order: {{order}}"
+    },
+    "expected": {
+      "message": {
+        "role": "user",
+        "content": [
+          {
+            "type": "text",
+            "text": "Order: {\n  \"id\": 7,\n  \"paid\": true\n}"
+          }
+        ]
+      }
+    }
+  },
+  {
+    "description": "Array of objects delivered as a single connection is flattened",
+    "inputs": {
+      "variables": [
+        [
+          {
+            "first": "Ada"
+          },
+          {
+            "last": "Lovelace"
+          }
+        ]
+      ]
+    },
+    "settings": {
+      "role": "user",
+      "content": "{{first}} {{last}}"
+    },
+    "expected": {
+      "message": {
+        "role": "user",
+        "content": [
+          {
+            "type": "text",
+            "text": "Ada Lovelace"
+          }
+        ]
+      }
+    }
+  }
+]

package/nodes/object-merge/object-merge.config.json

@@ -8,8 +8,8 @@
     {
       "name": "objects",
       "display_name": "Objects",
-      "type": "object",
-      "description": "Objects to merge (later objects override earlier ones)",
+      "type": "object or array of objects",
+      "description": "Objects to merge, individually or as arrays of objects (later objects override earlier ones)",
       "required": true,
       "allow_multiple": true
     },

package/nodes/object-merge/object-merge.process.js

@@ -2,8 +2,12 @@ export default async ({ inputs, settings, config }) => {
   const objects = inputs.objects;
   const arrayMode = inputs.array_mode ?? "replace";
 
-  // Normalize to array
-  const objectList = Array.isArray(objects) ? objects : [objects];
+  // Normalize to a flat array. A single connection can deliver an array of
+  // objects, and a multi-connection input can deliver arrays alongside plain
+  // objects, so flatten one level before filtering.
+  const objectList = (Array.isArray(objects) ? objects : [objects]).flatMap(
+    (entry) => (Array.isArray(entry) ? entry : [entry])
+  );
 
   // Filter out non-objects
   const validObjects = objectList.filter(

package/nodes/object-merge/object-merge.tests.json

@@ -142,5 +142,17 @@
     "expected": {
       "merged": {"level1": {"level2": {"level3": {"a": 1, "b": 2, "c": 3}}}}
     }
+  },
+  {
+    "description": "Array of objects delivered as a single connection is flattened",
+    "inputs": {
+      "objects": [
+        [{"a": 1}, {"b": 2}],
+        {"c": 3}
+      ]
+    },
+    "expected": {
+      "merged": {"a": 1, "b": 2, "c": 3}
+    }
   }
 ]

package/nodes/string-template/string-template.config.json

@@ -14,8 +14,8 @@
     {
       "name": "variables",
       "display_name": "Variables",
-      "description": "Object containing variable values",
-      "type": "object",
+      "description": "Object containing variable values, or an array of such objects to merge",
+      "type": "object or array of objects",
       "required": true
     }
   ],

package/nodes/string-template/string-template.process.js

@@ -1,15 +1,43 @@
+/**
+ * Render a variable value for injection into the template.
+ * Strings pass through untouched; everything else is JSON encoded so that
+ * nested objects and arrays read as data instead of "[object Object]".
+ */
+const renderVariable = (value) => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    // Circular structures (or anything else JSON can't encode) fall back to
+    // the default coercion rather than failing the whole template.
+    return String(value);
+  }
+};
+
 export default async ({inputs, settings, config}) => {
 
   const template = String(inputs.template || "");
-  const variables = inputs.variables || {};
+
+  // The input may arrive as a single object, or as an array of objects when
+  // it's fed from an "array of objects" output. Merge arrays into one lookup.
+  const raw = inputs.variables || {};
+  const variables = Array.isArray(raw)
+    ? raw.reduce((acc, entry) => {
+        if (Array.isArray(entry)) return Object.assign(acc, ...entry.filter(e => e && typeof e === "object"));
+        if (entry && typeof entry === "object") return Object.assign(acc, entry);
+        return acc;
+      }, {})
+    : raw;
+
   const keepMissing = settings.keep_missing || false;
-  
+
   const text = template.replace(/\{([^}]+)\}/g, (match, key) => {
     if (key in variables) {
-      return String(variables[key]);
+      return renderVariable(variables[key]);
     }
     return keepMissing ? match : "";
   });
-  
+
   return { text };
-}; 
+};

package/nodes/string-template/string-template.tests.json

@@ -59,5 +59,57 @@
     "expected": {
       "text": "Hello World! "
     }
+  },
+  {
+    "description": "Object variable is JSON stringified, not [object Object]",
+    "inputs": {
+      "template": "Config: {config}",
+      "variables": {"config": {"host": "localhost", "port": 8080}}
+    },
+    "settings": {
+      "keep_missing": false
+    },
+    "expected": {
+      "text": "Config: {\n  \"host\": \"localhost\",\n  \"port\": 8080\n}"
+    }
+  },
+  {
+    "description": "Array variable is JSON stringified",
+    "inputs": {
+      "template": "Items: {items}",
+      "variables": {"items": [1, 2]}
+    },
+    "settings": {
+      "keep_missing": false
+    },
+    "expected": {
+      "text": "Items: [\n  1,\n  2\n]"
+    }
+  },
+  {
+    "description": "Array of objects input is merged into one lookup",
+    "inputs": {
+      "template": "{greeting} {name}!",
+      "variables": [{"greeting": "Hello"}, {"name": "World"}]
+    },
+    "settings": {
+      "keep_missing": false
+    },
+    "expected": {
+      "text": "Hello World!"
+    }
+  },
+  {
+    "description": "Null variable renders as empty string",
+    "inputs": {
+      "template": "Value: {value}.",
+      "variables": {"value": null}
+    },
+    "settings": {
+      "keep_missing": false
+    },
+    "expected": {
+      "text": "Value: ."
+    }
   }
 ] 

package/nodes/system-prompt/system-prompt.config.json

@@ -13,7 +13,7 @@
     {
       "name": "variables",
       "display_name": "Variables",
-      "type": "object",
+      "type": "object or array of objects",
       "allow_multiple": true,
       "description": "Connect key-value pairs to inject into any matched {{key}} in the text content."
     },

package/nodes/system-prompt/system-prompt.process.js

@@ -2,12 +2,35 @@
  * Process function for the System Prompt node.
  * Outputs a message object, containing the prompt text and system role and text
  */
+/**
+ * Render a variable value for injection into prompt text.
+ * Strings pass through untouched; everything else is JSON encoded so that
+ * nested objects and arrays read as data instead of "[object Object]".
+ */
+const renderVariable = (value) => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    // Circular structures (or anything else JSON can't encode) fall back to
+    // the default coercion rather than failing the whole prompt.
+    return String(value);
+  }
+};
+
 export default async ({inputs, settings, config}) => {
   // Initialize variables array if not provided
   if(!inputs.variables) {
     inputs.variables = [];
   }
 
+  // A single connection can deliver an array of key-value objects, so flatten
+  // one level before looking keys up.
+  const variables = (Array.isArray(inputs.variables) ? inputs.variables : [inputs.variables])
+    .flatMap(entry => Array.isArray(entry) ? entry : [entry])
+    .filter(entry => entry !== null && typeof entry === "object");
+
   // Get the base content from settings
   let baseContent = settings.content || "";
 
@@ -47,9 +70,9 @@ export default async ({inputs, settings, config}) => {
   // Process variables
   message.content[0].text = message.content[0].text.replace(/\{\{(.*?)\}\}/g, (match, p1) => {
     // look for a variable with the key p1
-    let variable = inputs.variables.find(variable => Object.keys(variable).find(key => key === p1));
+    let variable = variables.find(variable => Object.keys(variable).find(key => key === p1));
     if(variable) {
-      return variable[p1];
+      return renderVariable(variable[p1]);
     }
     return match;
   });

package/nodes/system-prompt/system-prompt.tests.json

@@ -0,0 +1,113 @@
+[
+  {
+    "description": "String variable is injected as-is",
+    "inputs": {
+      "variables": [
+        {
+          "name": "Ada"
+        }
+      ]
+    },
+    "settings": {
+      "content": "Hello {{name}}!"
+    },
+    "expected": {
+      "message": {
+        "role": "system",
+        "content": [
+          {
+            "type": "text",
+            "text": "Hello Ada!"
+          }
+        ]
+      },
+      "prompt": "Hello Ada!"
+    }
+  },
+  {
+    "description": "Nested object variable is JSON stringified, not [object Object]",
+    "inputs": {
+      "variables": [
+        {
+          "profile": {
+            "name": "Ada",
+            "langs": [
+              "js",
+              "py"
+            ]
+          }
+        }
+      ]
+    },
+    "settings": {
+      "content": "Profile: {{profile}}"
+    },
+    "expected": {
+      "message": {
+        "role": "system",
+        "content": [
+          {
+            "type": "text",
+            "text": "Profile: {\n  \"name\": \"Ada\",\n  \"langs\": [\n    \"js\",\n    \"py\"\n  ]\n}"
+          }
+        ]
+      },
+      "prompt": "Profile: {\n  \"name\": \"Ada\",\n  \"langs\": [\n    \"js\",\n    \"py\"\n  ]\n}"
+    }
+  },
+  {
+    "description": "Array of objects delivered as a single connection is flattened",
+    "inputs": {
+      "variables": [
+        [
+          {
+            "first": "Ada"
+          },
+          {
+            "last": "Lovelace"
+          }
+        ]
+      ]
+    },
+    "settings": {
+      "content": "{{first}} {{last}}"
+    },
+    "expected": {
+      "message": {
+        "role": "system",
+        "content": [
+          {
+            "type": "text",
+            "text": "Ada Lovelace"
+          }
+        ]
+      },
+      "prompt": "Ada Lovelace"
+    }
+  },
+  {
+    "description": "Unmatched placeholder is left intact",
+    "inputs": {
+      "variables": [
+        {
+          "name": "Ada"
+        }
+      ]
+    },
+    "settings": {
+      "content": "Hello {{missing}}!"
+    },
+    "expected": {
+      "message": {
+        "role": "system",
+        "content": [
+          {
+            "type": "text",
+            "text": "Hello {{missing}}!"
+          }
+        ]
+      },
+      "prompt": "Hello {{missing}}!"
+    }
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",
@@ -11,7 +11,11 @@
     "tiktoken": "^1.0.22",
     "uuid": "^11.1.0"
   },
-  "repository": "https://github.com/zerowidth-ai/workbench-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zerowidth-ai/workbench-sdk.git",
+    "directory": "sdks/nodejs"
+  },
   "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": [
@@ -34,7 +38,8 @@
     "test-nodes": "node tests/test.all-nodes.js",
     "test-flows": "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"
+    "test-kb": "node tests/test.kb-search.js && node tests/test.kb-graph.js",
+    "test-custom-inference": "node tests/test.custom-inference.js"
   },
   "author": "Peter Binggeser @ ZeroWidth, LLC",
   "license": "Apache-2.0",

package/src/integrations/openrouter.js

@@ -1,18 +1,38 @@
-import OpenAI from 'openai';
+import OpenAI, { AzureOpenAI } from 'openai';
 import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
 
 export default class OpenRouterIntegration {
     constructor(apiKey, options = {}) {
-        
-        this.client = new OpenAI({
-            baseURL: options.baseURL || 'https://openrouter.ai/api/v1',
-            apiKey: apiKey,
-            defaultHeaders: {
-                'Content-Type': 'application/json',
-                'HTTP-Referer': options.referer || 'https://workbench.zerowidth.ai',
-                'X-Title': options.title || 'Workbench by ZeroWidth'
-            }
-        });
+        // dialect: 'openrouter' (default — the platform endpoint, which
+        // accepts OpenRouter-specific payload extensions), or a custom
+        // OpenAI-compatible endpoint: 'openai' (vLLM/Ollama/TGI/gateways)
+        // or 'azure' (Azure OpenAI — deployment routing + api-version).
+        // See ADR 0048 Phase 3 in the zerowidth monorepo.
+        this.dialect = options.dialect || 'openrouter';
+
+        const defaultHeaders = {
+            'Content-Type': 'application/json',
+            'HTTP-Referer': options.referer || 'https://workbench.zerowidth.ai',
+            'X-Title': options.title || 'Workbench by ZeroWidth'
+        };
+
+        if (this.dialect === 'azure') {
+            // Azure OpenAI: the model name is the deployment; auth is the
+            // `api-key` header + a required `api-version`. AzureOpenAI wires
+            // all three from these options.
+            this.client = new AzureOpenAI({
+                endpoint: options.baseURL,
+                apiKey: apiKey,
+                apiVersion: options.apiVersion || '2024-10-21',
+                defaultHeaders
+            });
+        } else {
+            this.client = new OpenAI({
+                baseURL: options.baseURL || 'https://openrouter.ai/api/v1',
+                apiKey: apiKey,
+                defaultHeaders
+            });
+        }
     }
 
     async chatCompletion(params, nodeConfig = null, engineConfig = null) {
@@ -24,16 +44,20 @@ export default class OpenRouterIntegration {
         } = params;
 
         // Base payload with required fields
-        const payload = {
-            model,
-            provider: {
+        const payload = { model };
+        // OpenRouter-only extensions: the `provider` routing directive and
+        // usage accounting. A custom OpenAI-compatible / Azure endpoint
+        // doesn't understand these and strict servers (Azure) reject
+        // unknown fields — so only send them to the platform endpoint.
+        if (this.dialect === 'openrouter') {
+            payload.provider = {
                 data_collection: "deny",
                 require_parameters: true,
-            },
+            };
             // Request OpenRouter usage accounting so the response carries the
             // authoritative cost (usage.cost). buildCostData prefers it.
-            usage: { include: true }
-        };
+            payload.usage = { include: true };
+        }
 
         // Add messages or prompt (required)
         if (messages) {

package/src/utilities/loaders.js

@@ -112,13 +112,27 @@ export async function loadNodes(flow) {
 export async function loadIntegrations(config, flow = null) {
   const integrations = {};
   
-  // Load OpenRouter integration if API key is provided
-  if (config.keys?.openrouter) {
+  // Load the primary LLM integration (OpenAI-compatible chat/completions).
+  // Public config is provider-agnostic — `inferenceBaseURL` + `keys.inference`
+  // — so a self-hosted host can point the engine at its own endpoint without
+  // any "openrouter" branding. `openrouterBaseURL` + `keys.openrouter` remain
+  // as backward-compatible aliases (the platform default endpoint stays
+  // OpenRouter). The integration is still registered under `openrouter` for
+  // the LLM nodes that look it up by that name.
+  const inferenceKey = config.keys?.inference ?? config.keys?.openrouter;
+  if (inferenceKey) {
       const openrouterPath = path.join(getDirname(import.meta.url), '../integrations', 'openrouter.js');
+      const inferenceBaseURL = config.inferenceBaseURL || config.openrouterBaseURL || 'https://openrouter.ai/api/v1';
+      // Only the real OpenRouter endpoint understands the OpenRouter-only
+      // payload extensions (provider routing, usage accounting). A custom
+      // base URL is a plain OpenAI-compatible endpoint, so use the 'openai'
+      // dialect there and don't send those fields (see openrouter.js).
+      const isOpenRouterEndpoint = /^https?:\/\/openrouter\.ai(\/|$)/i.test(inferenceBaseURL);
       try {
           const OpenRouterIntegration = await import(openrouterPath).then(module => module.default);
-          integrations.openrouter = new OpenRouterIntegration(config.keys.openrouter, {
-              baseURL: config.openrouterBaseURL || 'https://openrouter.ai/api/v1',
+          integrations.openrouter = new OpenRouterIntegration(inferenceKey, {
+              baseURL: inferenceBaseURL,
+              dialect: isOpenRouterEndpoint ? 'openrouter' : 'openai',
               referer: 'https://workbench.zerowidth.ai',
               title: 'Workbench by ZeroWidth'
           });
@@ -126,7 +140,28 @@ export async function loadIntegrations(config, flow = null) {
           throw error;
       }
   }
-  
+
+  // Bring-your-own inference endpoints (ADR 0048 Phase 3). The host passes
+  // `customInferenceProviders: { <name>: { baseURL, apiKey, dialect,
+  // apiVersion?, models? } }`. Each becomes an integration keyed
+  // `custom:<name>`, reusing the OpenRouter integration's completion logic
+  // with a custom destination + dialect. The `custom-inference` node
+  // resolves `custom:<provider>` by its settings.
+  if (config.customInferenceProviders && typeof config.customInferenceProviders === 'object') {
+      const openrouterPath = path.join(getDirname(import.meta.url), '../integrations', 'openrouter.js');
+      const OpenRouterIntegration = await import(openrouterPath).then(module => module.default);
+      for (const [name, provider] of Object.entries(config.customInferenceProviders)) {
+          if (!provider?.baseURL || !provider?.apiKey) continue;
+          integrations['custom:' + name] = new OpenRouterIntegration(provider.apiKey, {
+              baseURL: provider.baseURL,
+              dialect: provider.dialect === 'azure' ? 'azure' : 'openai',
+              apiVersion: provider.apiVersion,
+              referer: 'https://workbench.zerowidth.ai',
+              title: 'Workbench by ZeroWidth'
+          });
+      }
+  }
+
   // Load knowledge base integration if available
   const knowledgeBaseType = config.knowledgeBase?.type || 'sqlite';
   const knowledgeBaseConfig = config.knowledgeBase || {};