@zerowidth/workbench-sdk 2.3.0 → 2.5.0

package/nodes/x-ai-grok-4-7/x-ai-grok-4-7.process.js

@@ -0,0 +1,139 @@
+export default async ({inputs, settings, config, nodeConfig}) => {
+    try {
+        // Get OpenRouter integration from engine
+        const openrouter = config.integrations?.openrouter;
+        if (!openrouter) {
+            throw new Error("OpenRouter integration not found");
+        }
+
+        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 config inputs
+        const params = {};
+        const configInputs = [{"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":"reasoning","display_name":"Reasoning","type":"boolean","description":"Enable reasoning mode","default":null},{"name":"response_format","display_name":"Response Format","type":"object","description":"Output format specification","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":"seed","display_name":"Seed","type":"number","description":"Deterministic outputs","default":null},{"name":"logprobs","display_name":"Logprobs","type":"boolean","description":"Return log probabilities of the output tokens","default":null},{"name":"top_logprobs","display_name":"Top Logprobs","type":"number","description":"Number of most likely tokens to return at each position (0-20). Requires logprobs to be enabled.","default":null}];
+        
+        for (const input of configInputs) {
+
+            if(input.name === 'messages') continue;
+
+            const value = inputs[input.name];
+            if (value !== null && value !== undefined) {
+                // Flatten tools array to handle both individual tools and arrays of tools
+                if (input.name === 'tools' && Array.isArray(value)) {
+                    params.tools = value.flat();
+                } else {
+                    params[input.name] = value;
+                }
+            }
+        }
+
+        
+
+        const response = await openrouter.chatCompletion({
+            model: "x-ai/grok-4.7",
+            messages: messages,
+            ...params
+        }, nodeConfig, config);
+
+        // Get the set of internal tool names (tools handled by engine plugins)
+        // If internal_tool_names is undefined, we're in backward-compatible mode (include all)
+        // If it's an empty array, there are no internal tools (include none from history)
+        const hasInternalToolTracking = config.internal_tool_names !== undefined;
+        const internalToolNames = new Set(config.internal_tool_names || []);
+
+        // Build conversation output: only include messages related to internal tools
+        let conversationMessages = [];
+
+        if (Array.isArray(messages) && messages.length > 0) {
+            // Work backwards from the end
+            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) {
+                    // Only include tool result if it's for an internal tool
+                    const toolName = msg.name;
+                    if (!hasInternalToolTracking || internalToolNames.has(toolName)) {
+                        conversationMessages.unshift(msg);
+                    }
+                    // Skip external tool results
+                } else if (hasToolCalls) {
+                    // Filter to only internal tool calls
+                    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
+                        });
+                    }
+                    // External tool calls from history are dropped
+                } else {
+                    // Stop when we hit a message that is not tool and has no tool_calls
+                    break;
+                }
+            }
+        }
+
+        // Append the final output message — always include all tool_calls on the response
+        // The internal/external split only applies to historical messages above, not the fresh response
+        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);
+
+        const conversation = conversationMessages;
+
+        return {
+            conversation: conversation,
+            message: {
+                content: response.content,
+                role: response.role,
+                tool_calls: response.tool_calls
+            },
+            content: response.content,
+            role: response.role,
+            tool_calls: response.tool_calls,
+            reasoning: response.reasoning,
+            refusal: response.refusal,
+            logprobs: response.logprobs,
+            finish_reason: response.finish_reason,
+            usage: response.usage,
+            cost_total: response.cost_total,
+            cost_itemized: response.cost_itemized
+        };
+    } catch (error) {
+        console.log('error', error);
+        throw new Error(`SpaceXAI: Grok 4.7 node error: ${error.message}`);
+    }
+};

package/nodes/x-ai-grok-build-0-1/x-ai-grok-build-0-1.config.json

@@ -1,22 +1,19 @@
 {
-  "display_name": "xAI: Grok Build 0.1",
+  "display_name": "SpaceXAI: Grok Build 0.1",
   "tagline": "Generate text",
-  "description": "Grok Build 0.1 is xAI’s fast coding model trained specifically for agentic software engineering workflows. It supports text and image inputs with text output, and is optimized for interactive coding...",
+  "description": "Grok Build 0.1 is SpaceXAI’s fast coding model trained specifically for agentic software engineering workflows. It supports text and image inputs with text output, and is optimized for interactive coding...",
   "category": "llm",
   "provider": "x-ai",
   "accepts_plugins": true,
   "model_id": "x-ai/grok-build-0.1",
   "context_length": 256000,
   "supported_parameters": [
-    "frequency_penalty",
     "include_reasoning",
     "logprobs",
     "max_tokens",
-    "presence_penalty",
     "reasoning",
     "response_format",
     "seed",
-    "stop",
     "structured_outputs",
     "temperature",
     "tool_choice",
@@ -68,13 +65,6 @@
       "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",
@@ -96,20 +86,6 @@
       "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",

package/nodes/x-ai-grok-build-0-1/x-ai-grok-build-0-1.process.js

@@ -26,7 +26,7 @@ export default async ({inputs, settings, config, nodeConfig}) => {
 
         // Build parameters object from config inputs
         const params = {};
-        const configInputs = [{"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":"reasoning","display_name":"Reasoning","type":"boolean","description":"Enable reasoning mode","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},{"name":"logprobs","display_name":"Logprobs","type":"boolean","description":"Return log probabilities of the output tokens","default":null},{"name":"top_logprobs","display_name":"Top Logprobs","type":"number","description":"Number of most likely tokens to return at each position (0-20). Requires logprobs to be enabled.","default":null}];
+        const configInputs = [{"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":"reasoning","display_name":"Reasoning","type":"boolean","description":"Enable reasoning mode","default":null},{"name":"response_format","display_name":"Response Format","type":"object","description":"Output format specification","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":"seed","display_name":"Seed","type":"number","description":"Deterministic outputs","default":null},{"name":"logprobs","display_name":"Logprobs","type":"boolean","description":"Return log probabilities of the output tokens","default":null},{"name":"top_logprobs","display_name":"Top Logprobs","type":"number","description":"Number of most likely tokens to return at each position (0-20). Requires logprobs to be enabled.","default":null}];
         
         for (const input of configInputs) {
 
@@ -134,6 +134,6 @@ export default async ({inputs, settings, config, nodeConfig}) => {
         };
     } catch (error) {
         console.log('error', error);
-        throw new Error(`xAI: Grok Build 0.1 node error: ${error.message}`);
+        throw new Error(`SpaceXAI: Grok Build 0.1 node error: ${error.message}`);
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",
@@ -16,11 +16,17 @@
     "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.",
+  "homepage": "https://github.com/zerowidth-ai/workbench-sdk#readme",
+  "bugs": "https://github.com/zerowidth-ai/workbench-sdk/issues",
+  "description": "Workbench SDK — execute Workbench-authored flows in production. Successor to the zv1 package; see https://zerowidth.ai for the design surface.",
   "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
   "files": [
     "src/",
     "nodes/",
+    "!nodes/**/*.tests.json",
     "types/",
     "LICENSE",
     "README.md"
@@ -35,11 +41,13 @@
     "dotenv": "^17.2.2"
   },
   "scripts": {
+    "test": "node tests/test.all-nodes.js",
     "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-custom-inference": "node tests/test.custom-inference.js"
+    "test-custom-inference": "node tests/test.custom-inference.js",
+    "test-memory": "node tests/test.agent-memory.js"
   },
   "author": "Peter Binggeser @ ZeroWidth, LLC",
   "license": "Apache-2.0",

package/src/index.js

@@ -3259,3 +3259,13 @@ export default class Workbench {
 // pass an instance via `config.knowledgeBase.instance` (flow-global)
 // or `config.knowledgeBase.instances[kbUuid]` (per Knowledge Base node).
 export { KnowledgeBaseInterface } from './integrations/knowledge-base-interface.js';
+
+// Agent memory: implement MemoryStoreInterface over your own store and
+// pass it as `config.memory.instance`, or pass `config.memory.path` for
+// a folder of markdown. See integrations/memory-store.js.
+export {
+  MemoryStoreInterface,
+  FolderMemoryStore,
+  InMemoryMemoryStore,
+  normalizeMemoryPath,
+} from './integrations/memory-store.js';

package/src/integrations/memory-store.js

@@ -0,0 +1,294 @@
+/**
+ * Agent memory: a small folder of markdown an agent reads and writes
+ * between conversations.
+ *
+ *   MEMORY.md            a short index, read into the prompt every turn
+ *   memory/<topic>.md    detail, read when the agent decides it needs it
+ *   people/<id>.md       optional: one person's private page in a shared
+ *                        memory, read in only when they're talking
+ *
+ * A memory store is four operations over those paths. The SDK ships a
+ * folder store and an in-memory store; a host keeping many agents'
+ * memories implements the same four over whatever it has (SQL rows,
+ * bucket objects, Redis) and passes it as `config.memory.instance`.
+ * Each store instance is one memory: the host decides whose (an
+ * agent's own, one end user's) before handing it to the engine.
+ *
+ * The memory nodes (Memory, memory_list/read/write/edit/delete) only
+ * ever talk to `config.integrations.memory`, which is the host's store
+ * wrapped in `ScopedMemory` so every store gets the same path rules
+ * and size limits.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const MEMORY_INDEX = "MEMORY.md";
+export const MAX_FILE_BYTES = 100_000;
+export const MAX_FILES = 200;
+
+const SEGMENT = /^[a-z0-9][a-z0-9._-]*$/i;
+
+/** The node types that read or write an agent's memory. */
+export const MEMORY_NODE_TYPES = new Set([
+  "memory",
+  "memory-list",
+  "memory-read",
+  "memory-write",
+  "memory-edit",
+  "memory-delete",
+]);
+
+export function flowUsesMemory(flow) {
+  return Array.isArray(flow?.nodes) && flow.nodes.some((n) => MEMORY_NODE_TYPES.has(n.type));
+}
+
+export class MemoryPathError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MemoryPathError";
+  }
+}
+
+/**
+ * Normalize and check a memory path. Accepts `MEMORY.md`,
+ * `memory/<name>.md` and `people/<id>.md`, adding `.md` when missing.
+ * Nothing nests deeper than one folder.
+ */
+export function normalizeMemoryPath(raw) {
+  const trimmed = String(raw ?? "").trim().replace(/^\.?\/+/, "");
+  const withExt = /\.md$/i.test(trimmed) ? trimmed : `${trimmed}.md`;
+  const parts = withExt.split("/");
+  const ok =
+    (parts.length === 1 && parts[0] === MEMORY_INDEX) ||
+    (parts.length === 2 &&
+      (parts[0] === "memory" || parts[0] === "people") &&
+      SEGMENT.test(parts[1]) &&
+      !parts[1].includes(".."));
+  if (!ok) {
+    throw new MemoryPathError(
+      `"${raw}" isn't a memory file. Use MEMORY.md, memory/<topic>.md, or people/<id>.md.`,
+    );
+  }
+  return withExt;
+}
+
+/**
+ * The contract every memory store implements. Paths arrive already
+ * normalized. `origin` says which node made the change, for stores
+ * that keep a history.
+ *
+ * Optional members a host store may add:
+ *   held     true when changes wait for a person to approve them;
+ *            write/delete then return { status: "held" }.
+ *   pending()  how many changes are waiting, for the prompt.
+ */
+export class MemoryStoreInterface {
+  /** @returns {Promise<Array<{path: string, size: number, updated_at?: string}>>} */
+  async list() {
+    throw new Error("list() must be implemented by a memory store");
+  }
+
+  /** @returns {Promise<string|null>} the file's content, or null when it doesn't exist */
+  async read(_path) {
+    throw new Error("read() must be implemented by a memory store");
+  }
+
+  /** @returns {Promise<{status: "applied"|"held"}>} */
+  async write(_path, _content, _origin) {
+    throw new Error("write() must be implemented by a memory store");
+  }
+
+  /** @returns {Promise<{status: "applied"|"held"}>} */
+  async delete(_path, _origin) {
+    throw new Error("delete() must be implemented by a memory store");
+  }
+}
+
+/** Memory that lasts as long as the process. For tests and trials. */
+export class InMemoryMemoryStore extends MemoryStoreInterface {
+  constructor(files = {}) {
+    super();
+    this.files = new Map(Object.entries(files));
+  }
+
+  async list() {
+    return [...this.files.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([p, content]) => ({ path: p, size: Buffer.byteLength(content, "utf8") }));
+  }
+
+  async read(p) {
+    return this.files.has(p) ? this.files.get(p) : null;
+  }
+
+  async write(p, content) {
+    this.files.set(p, content);
+    return { status: "applied" };
+  }
+
+  async delete(p) {
+    this.files.delete(p);
+    return { status: "applied" };
+  }
+}
+
+/** Memory as real files under a folder: `<root>/MEMORY.md`, … */
+export class FolderMemoryStore extends MemoryStoreInterface {
+  constructor(root) {
+    super();
+    if (!root) throw new Error("FolderMemoryStore needs a folder path.");
+    this.root = path.resolve(root);
+  }
+
+  async list() {
+    const out = [];
+    const visit = async (rel) => {
+      let entries;
+      try {
+        entries = await fs.readdir(path.join(this.root, rel), { withFileTypes: true });
+      } catch (err) {
+        if (err.code === "ENOENT") return;
+        throw err;
+      }
+      for (const entry of entries) {
+        const p = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory() && !rel && (entry.name === "memory" || entry.name === "people")) {
+          await visit(p);
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          try {
+            normalizeMemoryPath(p);
+          } catch {
+            continue;
+          }
+          const stat = await fs.stat(path.join(this.root, p));
+          out.push({ path: p, size: stat.size, updated_at: stat.mtime.toISOString() });
+        }
+      }
+    };
+    await visit("");
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  async read(p) {
+    try {
+      return await fs.readFile(path.join(this.root, p), "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    }
+  }
+
+  async write(p, content) {
+    const full = path.join(this.root, p);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, "utf8");
+    return { status: "applied" };
+  }
+
+  async delete(p) {
+    await fs.rm(path.join(this.root, p), { force: true });
+    return { status: "applied" };
+  }
+}
+
+/**
+ * The store the memory nodes see: path rules and size limits in front
+ * of whatever store the host passed, so a custom store can't be handed
+ * `../../etc/passwd` and doesn't have to re-implement the limits.
+ *
+ * People pages (`people: true`, a shared memory with a page per person):
+ * the agent sees and changes only the page of whoever is talking
+ * (`person`), so one person's notes never reach another conversation.
+ * With nobody talking it sees no pages at all. Without `people`, the
+ * `people/` folder isn't part of the memory.
+ */
+export class ScopedMemory {
+  constructor(store, { people = false, person = null } = {}) {
+    this.store = store;
+    this.people = people === true;
+    this.talking = this.people && person?.id ? { id: String(person.id), name: person.name || String(person.id) } : null;
+    // The id becomes a file name; an id that can't be one would leave
+    // the agent pointed at a page it isn't allowed to write.
+    if (this.talking && (!SEGMENT.test(`${this.talking.id}.md`) || this.talking.id.includes(".."))) {
+      throw new MemoryPathError(
+        `memory.person.id "${this.talking.id}" can't name a page: use letters, digits, ".", "_" and "-" (hash or slug an email first).`,
+      );
+    }
+  }
+
+  /** Whoever is talking, when this memory keeps a page per person. */
+  get person() {
+    return this.talking;
+  }
+
+  get held() {
+    return this.store.held === true;
+  }
+
+  /** The canonical form of a path the agent may use, or a MemoryPathError. */
+  normalize(raw) {
+    const p = normalizeMemoryPath(raw);
+    if (!p.startsWith("people/")) return p;
+    if (!this.people) {
+      throw new MemoryPathError(`"${raw}" isn't a memory file. Use MEMORY.md or memory/<topic>.md.`);
+    }
+    if (!this.talking || p !== `people/${this.talking.id}.md`) {
+      throw new MemoryPathError(
+        this.talking
+          ? `You can only use the page of the person you're talking to: people/${this.talking.id}.md.`
+          : "Nobody is named in this conversation, so there's no person's page to use.",
+      );
+    }
+    return p;
+  }
+
+  async pending() {
+    return typeof this.store.pending === "function" ? await this.store.pending() : 0;
+  }
+
+  async list() {
+    const own = this.talking ? `people/${this.talking.id}.md` : null;
+    return (await this.store.list()).filter((f) => !f.path.startsWith("people/") || f.path === own);
+  }
+
+  async read(raw) {
+    return this.store.read(this.normalize(raw));
+  }
+
+  async write(raw, content, origin = {}) {
+    const p = this.normalize(raw);
+    const text = String(content ?? "");
+    if (Buffer.byteLength(text, "utf8") > MAX_FILE_BYTES) {
+      throw new MemoryPathError(
+        `${p} would be over ${MAX_FILE_BYTES / 1000}KB. Keep memory files short; split detail into another topic file.`,
+      );
+    }
+    const existing = await this.store.list();
+    if (!existing.some((f) => f.path === p) && existing.length >= MAX_FILES) {
+      throw new MemoryPathError(
+        `Memory already holds ${MAX_FILES} files. Fold some together or delete ones that no longer matter.`,
+      );
+    }
+    return this.store.write(p, text, origin);
+  }
+
+  async delete(raw, origin = {}) {
+    return this.store.delete(this.normalize(raw), origin);
+  }
+}
+
+/**
+ * Pick the memory for a run from `config.memory`:
+ *   { instance }  a host store (wins)
+ *   { path }      a FolderMemoryStore at that folder
+ *   neither       an in-memory store, gone when the process exits
+ * plus `people: true` and `person: { id, name }` for a shared memory
+ * with a page per person.
+ */
+export function createMemory(memoryConfig = {}) {
+  const options = { people: memoryConfig.people, person: memoryConfig.person };
+  if (memoryConfig.instance) return new ScopedMemory(memoryConfig.instance, options);
+  if (memoryConfig.path) return new ScopedMemory(new FolderMemoryStore(memoryConfig.path), options);
+  return new ScopedMemory(new InMemoryMemoryStore(), options);
+}