@zerowidth/workbench-sdk 2.1.2 → 2.2.0

package/src/index.js

@@ -197,6 +197,26 @@ export default class Workbench {
     this.flowTimeout = null;
     this.timeline = [];
 
+    // Idle watchdog state (see run()). `touchActivity()` stamps
+    // progress; a sub-engine created by this engine gets
+    // `_notifyParentActivity` wired so descendant progress keeps the
+    // whole ancestor chain alive.
+    this.idleWatchdog = null;
+    this._lastActivityAt = 0;
+    this._notifyParentActivity = null;
+
+    // Token deltas are progress too — the LLM integrations call
+    // config.onNodeUpdate directly, so wrap it once here to stamp
+    // activity before forwarding to the consumer's handler (if any).
+    // A model streaming a long completion is alive, not idle.
+    {
+      const consumerOnNodeUpdate = this.config.onNodeUpdate || null;
+      this.config.onNodeUpdate = (event) => {
+        this.touchActivity();
+        return consumerOnNodeUpdate ? consumerOnNodeUpdate(event) : undefined;
+      };
+    }
+
     // Initialize ErrorManager for centralized error handling
     this.errorManager = new ErrorManager({
       onError: this.config.onError || null,
@@ -429,8 +449,11 @@ export default class Workbench {
       startTime: new Date().toISOString()
     };
     const startDate = new Date();
-    
+
     try {
+      // Every node-execution boundary is progress for the idle
+      // watchdog — entry here, plus the success/error exits below.
+      this.touchActivity();
       if(this.config.onNodeStart) {
         await this.config.onNodeStart({
           nodeId: node.id,
@@ -474,7 +497,8 @@ export default class Workbench {
       timelineEntry.durationMs = endDate - startDate;
       timelineEntry.status = 'success';
       this.timeline.push(timelineEntry);
-      
+      this.touchActivity();
+
       if(this.config.onNodeComplete) {
         await this.config.onNodeComplete({
           nodeId: node.id,
@@ -494,7 +518,8 @@ export default class Workbench {
       timelineEntry.status = 'error';
       timelineEntry.errorMessage = error.message;
       this.timeline.push(timelineEntry);
-      
+      this.touchActivity();
+
       // Update execution context for ErrorManager
       this.errorManager.updateExecutionContext({
         timeline: this.timeline,
@@ -1230,6 +1255,22 @@ export default class Workbench {
    * @param {number} timeout - Maximum execution time in milliseconds
    * @returns {Object} The final output from output nodes
    */
+  /**
+   * Stamp forward progress for the idle watchdog (see run()). Called
+   * from every node-execution boundary, every tool-call dispatch and
+   * settle, and every streaming token delta. Chains upward: when this
+   * engine is a sub-engine (macro / imported flow), the parent wired
+   * `_notifyParentActivity` at construction so descendant progress
+   * keeps every ancestor's watchdog fed — a parent awaiting a hard-
+   * working sub-agent is not idle.
+   */
+  touchActivity() {
+    this._lastActivityAt = Date.now();
+    if (typeof this._notifyParentActivity === 'function') {
+      this._notifyParentActivity();
+    }
+  }
+
   async run(inputData, timeout = 60000) {
     this.logDebug(`Starting flow execution with timeout: ${timeout}ms`);
     this.logDebug(`Input data:`, JSON.stringify(inputData, null, 2));
@@ -1283,6 +1324,36 @@ export default class Workbench {
       }
     }, timeout);
 
+    // Idle watchdog (opt-in via config.idleTimeoutMs). The flow
+    // timeout above is a wall-clock cap on the WHOLE run — one budget
+    // that a multi-round agent legitimately eats with many quick tool
+    // calls. The watchdog instead bounds time-without-progress: every
+    // node boundary / tool dispatch / tool settle / token delta calls
+    // touchActivity(), and only silence longer than idleTimeoutMs
+    // aborts. Hosts pair a short idle bound (e.g. 60s) with a long
+    // wall-clock cap so busy flows finish and hung flows still die
+    // fast. Uses the same hasTimedOut + abort path as the flow
+    // timeout so downstream status handling is identical.
+    const idleTimeoutMs = typeof this.config.idleTimeoutMs === 'number' && this.config.idleTimeoutMs > 0
+      ? this.config.idleTimeoutMs
+      : null;
+    if (idleTimeoutMs !== null) {
+      this._lastActivityAt = Date.now();
+      const checkEveryMs = Math.min(1000, Math.max(50, Math.floor(idleTimeoutMs / 4)));
+      this.idleWatchdog = setInterval(() => {
+        if (Date.now() - this._lastActivityAt <= idleTimeoutMs) return;
+        this.logDebug("Flow execution idle-timed out (no progress)");
+        this.hasTimedOut = true;
+        if (!this.abortController.signal.aborted) {
+          this.abortController.abort(new Error(
+            `Flow execution timed out after ${idleTimeoutMs}ms without progress (idle timeout)`,
+          ));
+        }
+        clearInterval(this.idleWatchdog);
+        this.idleWatchdog = null;
+      }, checkEveryMs);
+    }
+
     let inputsMissingValues = [];
 
     try {
@@ -1544,6 +1615,7 @@ export default class Workbench {
       
       this.logDebug("Flow execution complete. Final outputs:", finalOutputs);
       clearTimeout(this.flowTimeout);
+      if (this.idleWatchdog) { clearInterval(this.idleWatchdog); this.idleWatchdog = null; }
 
       return {
         outputs: finalOutputs,
@@ -1555,6 +1627,7 @@ export default class Workbench {
     } catch (error) {
       // Clear the timeout on error
       clearTimeout(this.flowTimeout);
+      if (this.idleWatchdog) { clearInterval(this.idleWatchdog); this.idleWatchdog = null; }
       
       // If this is a timeout error, add it to the timeline
       if (error.errorType === 'timeout') {
@@ -1583,6 +1656,7 @@ export default class Workbench {
       throw error;
     } finally {
       clearTimeout(this.flowTimeout);
+      if (this.idleWatchdog) { clearInterval(this.idleWatchdog); this.idleWatchdog = null; }
       this._abortTeardown?.();
       // Restore the inherited signal so a reused engine doesn't treat this run's
       // (possibly aborted) signal as an ancestor on the next run().
@@ -1673,6 +1747,12 @@ export default class Workbench {
     
     // Share executed states with internal engine to prevent duplicate execution
     internalEngine.executedNodeStates = this.executedNodeStates;
+
+    // Chain idle-watchdog activity upward: a sub-engine making
+    // progress means this engine (awaiting it) is not idle. Without
+    // this, a parent with idleTimeoutMs would kill a hard-working
+    // sub-agent after one idle window of parent-level silence.
+    internalEngine._notifyParentActivity = () => this.touchActivity();
     
     // Initialize the internal engine
     await internalEngine.initialize();
@@ -2176,7 +2256,13 @@ export default class Workbench {
             toolSchemas.push(tool);
             toolNodeMap[tool.name] = { node: pluginNode, type: 'mcp', mcpToolName: tool.name };
             toolRunners[tool.name] = async (args) => {
-              return await callMCPTool({ ...args, name: tool.name }, { url, token });
+              // Tool identity and tool arguments stay separate — spreading
+              // args next to `name` clobbered any tool argument that was
+              // itself named `name` (caliper_datasets_create et al).
+              return await callMCPTool(
+                { name: tool.name, arguments: args },
+                { url, token },
+              );
             };
           }
           this.logDebug(`Loaded ${tools.length} MCP tools from "${integrationName}"`);
@@ -2310,6 +2396,8 @@ export default class Workbench {
                     await this.config.onNodeError({
                       nodeId: toolNodeInfo.node.id,
                       nodeType: toolNodeInfo.node.type,
+                      toolName,
+                      toolCallId: tool_call.id,
                       error: parseError
                     });
                   }
@@ -2333,11 +2421,20 @@ export default class Workbench {
               // multi-round tool-calling LLMs look like a single
               // long "LLM node running…" entry — the waterfall has
               // no visibility into the tool-call cycles inside.
+              //
+              // `toolName` / `toolCallId` ride on every tool-call
+              // event: nodeId/nodeType identify the integration node
+              // (shared by every tool on that MCP server), so without
+              // the model-invoked tool name a live UI can't label the
+              // chip, and without the call id it can't pair start →
+              // complete/error across a multi-round loop.
               if (toolNodeInfo?.node && this.config.onNodeStart) {
                 try {
                   await this.config.onNodeStart({
                     nodeId: toolNodeInfo.node.id,
                     nodeType: toolNodeInfo.node.type,
+                    toolName,
+                    toolCallId: tool_call.id,
                     inputs: toolArguments,
                   });
                 } catch (_hookErr) {
@@ -2345,9 +2442,14 @@ export default class Workbench {
                 }
               }
 
-              // Execute the tool runner with error handling
+              // Execute the tool runner with error handling. Dispatch
+              // and settle both stamp the idle watchdog — MCP tools
+              // call out directly (no _executeNodeCore boundary), so
+              // without these a tool-heavy round would read as silence.
+              this.touchActivity();
               try {
                 const toolResult = await toolRunners[toolName](toolArguments);
+                this.touchActivity();
 
                 // Success - push result
                 tool_results.push({
@@ -2380,6 +2482,8 @@ export default class Workbench {
                       await this.config.onNodeComplete({
                         nodeId: toolNodeInfo.node.id,
                         nodeType: toolNodeInfo.node.type,
+                        toolName,
+                        toolCallId: tool_call.id,
                         inputs: toolArguments,
                         outputs: { result: toolResult },
                       });
@@ -2391,6 +2495,7 @@ export default class Workbench {
 
               } catch (executionError) {
                 // Tool execution failed - create error result
+                this.touchActivity();
                 this.logDebug(`Tool execution failed for ${toolName}:`, executionError.message);
 
                 // Create timeline entry for the execution error
@@ -2413,6 +2518,8 @@ export default class Workbench {
                     await this.config.onNodeError({
                       nodeId: toolNodeInfo.node.id,
                       nodeType: toolNodeInfo.node.type,
+                      toolName,
+                      toolCallId: tool_call.id,
                       error: executionError
                     });
                   }

package/src/utilities/mcp.js

@@ -86,17 +86,37 @@ function parseMcpResponse(response) {
 
 /**
  * Call an MCP tool.
- * @param {Object} args - The arguments to pass to the tool (must include 'name')
+ *
+ * Tool identity and tool arguments are carried as SEPARATE fields —
+ * never merged into one flat object. The previous flat-object contract
+ * ({ ...toolArgs, name: toolName }) made a tool argument named `name`
+ * indistinguishable from the tool's own name: it was overwritten at
+ * the call site, then stripped here, so tools with a top-level `name`
+ * parameter received `name: undefined`. Any unexpected top-level key
+ * throws so a legacy-shape caller fails loudly instead of silently
+ * dropping arguments.
+ *
+ * @param {Object} call - { name: string, arguments?: Object } — the
+ *   tool's name and the model-provided arguments, forwarded verbatim.
  * @param {Object} options - { url, token }
  * @returns {Object} The result of the tool call
  */
-export async function callMCPTool(args, { url, token } = {}) {
+export async function callMCPTool(call, { url, token } = {}) {
   if (!url) throw new Error('No MCP URL provided');
 
-  const toolName = args.name;
+  const { name: toolName, arguments: toolArgs } = call ?? {};
   if (!toolName) throw new Error('No tool name provided for MCP call');
 
-  const { name, ...toolArgs } = args;
+  const extraKeys = Object.keys(call).filter(
+    (k) => k !== 'name' && k !== 'arguments',
+  );
+  if (extraKeys.length > 0) {
+    throw new Error(
+      `callMCPTool takes { name, arguments } — unexpected top-level keys: ` +
+      `${extraKeys.join(', ')}. Tool arguments belong under "arguments".`,
+    );
+  }
+
   const id = uuidv4();
 
   try {
@@ -108,7 +128,7 @@ export async function callMCPTool(args, { url, token } = {}) {
         method: 'tools/call',
         params: {
           name: toolName,
-          arguments: toolArgs,
+          arguments: toolArgs ?? {},
         },
       },
       {