@skilder-ai/runtime 0.7.3 → 0.7.5

package/dist/index.js

@@ -138392,6 +138392,7 @@ var McpServerStatus = /* @__PURE__ */ ((McpServerStatus2) => {
   McpServerStatus2["Connected"] = "CONNECTED";
   McpServerStatus2["Disconnected"] = "DISCONNECTED";
   McpServerStatus2["Error"] = "ERROR";
+  McpServerStatus2["Idle"] = "IDLE";
   McpServerStatus2["Pending"] = "PENDING";
   McpServerStatus2["Starting"] = "STARTING";
   return McpServerStatus2;
@@ -138461,6 +138462,34 @@ var WorkspaceRole = /* @__PURE__ */ ((WorkspaceRole2) => {
   return WorkspaceRole2;
 })(WorkspaceRole || {});
 
+// ../common/src/utils/parse-script-args.ts
+function parseScriptArgs(argsString) {
+  const args = [];
+  let current = "";
+  let inQuotes = false;
+  let quoteChar = "";
+  for (const char of argsString) {
+    if ((char === '"' || char === "'") && !inQuotes) {
+      inQuotes = true;
+      quoteChar = char;
+    } else if (char === quoteChar && inQuotes) {
+      inQuotes = false;
+      quoteChar = "";
+    } else if (char === " " && !inQuotes) {
+      if (current) {
+        args.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) {
+    args.push(current);
+  }
+  return args;
+}
+
 // ../common/src/related-content-detector.ts
 function escapeRegex2(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -144820,39 +144849,9 @@ For other resources, use the \`learn\` tool instead.`
       };
     }
     const script = scriptEntry;
-    const args = lookupArgs ? this.parseScriptArgs(lookupArgs) : [];
+    const args = lookupArgs ? parseScriptArgs(lookupArgs) : [];
     return await this.routeScriptToRuntime(script, skill, args);
   }
-  /**
-   * Parse script arguments from the path string.
-   * Arguments can be space-separated, with quoted strings supported.
-   */
-  parseScriptArgs(argsString) {
-    const args = [];
-    let current = "";
-    let inQuotes = false;
-    let quoteChar = "";
-    for (const char of argsString) {
-      if ((char === '"' || char === "'") && !inQuotes) {
-        inQuotes = true;
-        quoteChar = char;
-      } else if (char === quoteChar && inQuotes) {
-        inQuotes = false;
-        quoteChar = "";
-      } else if (char === " " && !inQuotes) {
-        if (current) {
-          args.push(current);
-          current = "";
-        }
-      } else {
-        current += char;
-      }
-    }
-    if (current) {
-      args.push(current);
-    }
-    return args;
-  }
   /**
    * Route script execution to a runtime via NATS.
    * Scripts always execute on the runtime linked to the script.
@@ -145178,34 +145177,68 @@ This file can be used with other file I/O tools that accept \`@skilder-file:/\`
     const lines = [];
     lines.push(`# Skill: ${skill.name}`);
     lines.push("");
+    lines.push(...this.formatSkillDetails(skill));
+    return {
+      response: { content: [{ type: "text", text: lines.join("\n") }] },
+      skillIds: [skill.id]
+    };
+  }
+  /**
+   * Format full details for a single skill including description, instructions, tool schemas,
+   * and referenced resources. Used by both handleLearnSkill and handleGetHat to ensure DRY
+   * consistency when rendering skill content.
+   *
+   * @param skill - The skill catalog entry to format
+   * @param options.headingLevel - Heading level for tools section (2 for standalone, 4 for within-hat)
+   * @param options.renderedToolNames - Set of tool names already rendered (for deduplication across skills in a hat)
+   */
+  formatSkillDetails(skill, options) {
+    const headingLevel = options?.headingLevel ?? 2;
+    const heading = "#".repeat(headingLevel);
+    const renderedToolNames = options?.renderedToolNames;
+    const firstSkillForTool = options?.firstSkillForTool;
+    const lines = [];
     if (skill.description) {
       lines.push(skill.description);
       lines.push("");
     }
     if (skill.instructions) {
-      lines.push("## Instructions");
+      lines.push(`${heading} Instructions`);
       lines.push(skill.instructions);
       lines.push("");
     }
     if (skill.toolNames.length > 0) {
-      lines.push("## Available Tools");
+      lines.push(`${heading} Available Tools`);
       lines.push("Use `call_tool` with the tool name and input to execute these tools:");
       lines.push("");
       for (const toolName of skill.toolNames) {
-        const tool2 = this.tools.getValue()?.find((t4) => t4.name === toolName);
-        if (tool2) {
-          lines.push(`### ${tool2.name}`);
-          lines.push(tool2.description || "No description");
-          lines.push("");
-          lines.push("**Input Schema:**");
-          lines.push("```json");
-          lines.push(JSON.stringify(tool2.inputSchema, null, 2));
-          lines.push("```");
+        const subHeading = "#".repeat(headingLevel + 1);
+        if (renderedToolNames?.has(toolName)) {
+          const firstSkill = firstSkillForTool?.get(toolName);
+          lines.push(`${subHeading} ${toolName}`);
+          lines.push(firstSkill ? `(schema shown above under ${firstSkill})` : "(schema shown above)");
           lines.push("");
         } else {
-          lines.push(`### ${toolName}`);
-          lines.push("Tool definition not available");
-          lines.push("");
+          if (renderedToolNames) {
+            renderedToolNames.add(toolName);
+            firstSkillForTool?.set(toolName, skill.name);
+          }
+          const tool2 = this.tools.getValue()?.find((t4) => t4.name === toolName);
+          if (tool2) {
+            lines.push(`${subHeading} ${tool2.name}`);
+            lines.push(tool2.description || "No description");
+            lines.push("");
+            lines.push("**Input Schema:**");
+            lines.push("```json");
+            lines.push(JSON.stringify(tool2.inputSchema, null, 2));
+            lines.push("```");
+            lines.push("");
+          } else {
+            this.logger.warn({ toolName, skillId: skill.id, toolsInitialized: this.tools.getValue() != null }, `Tool "${toolName}" referenced by skill "${skill.name}" not found in tools list`);
+            lines.push(`${subHeading} ${toolName}`);
+            lines.push("Tool definition not available");
+            lines.push("");
+          }
         }
       }
       lines.push('Call these tools using: `call_tool(tool_name="<name>", tool_input={...})`');
@@ -145221,10 +145254,7 @@ This file can be used with other file I/O tools that accept \`@skilder-file:/\`
     } catch (error48) {
       this.logger.warn({ error: error48, skillId: skill.id }, "Failed to detect related mentions in skill instructions");
     }
-    return {
-      response: { content: [{ type: "text", text: lines.join("\n") }] },
-      skillIds: [skill.id]
-    };
+    return lines;
   }
   /**
    * Handle feedback_skill tool call.
@@ -145496,27 +145526,19 @@ ${JSON.stringify(toolConfig.inputSchema, null, 2)}`
     }
     this.session.learnedHatIds.add(hat.id);
     const skills = [];
-    const allToolNames = /* @__PURE__ */ new Set();
     const missingSkillIds = [];
     for (const skillId of hat.skillIds) {
       const skill = this.catalog.skills.find((s) => s.id === skillId);
       if (skill) {
         this.session.learnedSkillIds.add(skill.id);
-        skills.push({
-          name: skill.name,
-          description: skill.description,
-          instructions: skill.instructions,
-          toolNames: skill.toolNames
-        });
-        for (const toolName of skill.toolNames) {
-          allToolNames.add(toolName);
-        }
+        skills.push(skill);
       } else {
-        this.logger.warn(`Skill ID "${skillId}" referenced in hat "${hat.name}" not found in catalog`);
+        this.logger.warn({ skillId, hatId: hat.id, hatName: hat.name }, "Skill referenced in hat not found in catalog");
         missingSkillIds.push(skillId);
       }
     }
-    this.logger.info(`User ${this.identity.id} retrieved hat "${hat.name}" with ${skills.length} skills and ${allToolNames.size} tools`);
+    const totalToolCount = new Set(skills.flatMap((s) => s.toolNames)).size;
+    this.logger.info(`User ${this.identity.id} retrieved hat "${hat.name}" with ${skills.length} skills and ${totalToolCount} tools`);
     const lines = [];
     lines.push(`# Hat: ${hat.name}`);
     lines.push("");
@@ -145532,43 +145554,18 @@ ${JSON.stringify(toolConfig.inputSchema, null, 2)}`
     if (skills.length > 0) {
       lines.push("## Skills Learned");
       lines.push("");
+      const renderedToolNames = /* @__PURE__ */ new Set();
+      const firstSkillForTool = /* @__PURE__ */ new Map();
       for (const skill of skills) {
         lines.push(`### ${skill.name}`);
-        if (skill.description) {
-          lines.push(skill.description);
-        }
-        if (skill.instructions) {
-          lines.push("");
-          lines.push("**Instructions:**");
-          lines.push(skill.instructions);
-        }
-        if (skill.toolNames.length > 0) {
-          lines.push("");
-          lines.push(`**Tools:** ${skill.toolNames.join(", ")}`);
-        }
+        lines.push(...this.formatSkillDetails(skill, { headingLevel: 4, renderedToolNames, firstSkillForTool }));
         lines.push("");
       }
     } else {
       lines.push("This hat contains no skills.");
       lines.push("");
     }
-    if (allToolNames.size > 0) {
-      lines.push("## All Available Tools");
-      lines.push("");
-      lines.push("The following tools are now available:");
-      for (const toolName of allToolNames) {
-        const tool2 = this.tools.getValue()?.find((t4) => t4.name === toolName);
-        if (tool2) {
-          lines.push(`- **${tool2.name}**: ${tool2.description || "No description"}`);
-        } else {
-          lines.push(`- **${toolName}**`);
-        }
-      }
-      lines.push("");
-      lines.push("You can now use these tools to help the user.");
-    }
     if (missingSkillIds.length > 0) {
-      lines.push("");
       lines.push("## Warning");
       lines.push("");
       lines.push(`Some skills referenced by this hat could not be loaded: ${missingSkillIds.join(", ")}`);
@@ -152628,10 +152625,29 @@ var ToolService = class ToolService2 extends Service {
     this.rxSubscriptions = [];
     this.sdkBundleContent = null;
     this.sdkBundleLoadPromise = null;
+    this.dormantConfigs = /* @__PURE__ */ new Map();
+    this.idleTimers = /* @__PURE__ */ new Map();
+    this.startingServers = /* @__PURE__ */ new Map();
+    this.stoppingServers = /* @__PURE__ */ new Map();
+    this.activationFailures = /* @__PURE__ */ new Map();
+    this.maxActivationRetries = 3;
+    this.activationCooldownMs = 6e4;
+    this.lazyStartEnabled = true;
+    this.idleTimeoutMs = 3e5;
     this.logger = this.loggerService.getLogger(this.name);
   }
   async initialize() {
     this.logger.info("Starting");
+    const lazyStartRaw = (process.env.MCP_LAZY_START ?? "true").toLowerCase();
+    this.lazyStartEnabled = !["false", "0", "no", "off"].includes(lazyStartRaw);
+    const parsedTimeout = parseInt(process.env.MCP_IDLE_TIMEOUT_MS ?? "300000", 10);
+    if (Number.isNaN(parsedTimeout) || parsedTimeout <= 0) {
+      this.logger.warn({ rawValue: process.env.MCP_IDLE_TIMEOUT_MS }, "Invalid MCP_IDLE_TIMEOUT_MS value, falling back to default 300000ms");
+      this.idleTimeoutMs = 3e5;
+    } else {
+      this.idleTimeoutMs = parsedTimeout;
+    }
+    this.logger.info({ lazyStart: this.lazyStartEnabled, idleTimeoutMs: this.idleTimeoutMs }, "Lazy-start configuration");
     await this.authService.waitForStarted();
     await this.natsService.waitForStarted();
     await this.healthService.waitForStarted();
@@ -152666,7 +152682,7 @@ var ToolService = class ToolService2 extends Service {
       this.natsService.publish(message);
       this.logger.debug(`Published MCP server status: ${mcpServerId} -> ${status}${error48 ? ` (${error48})` : ""}`);
     } catch (publishError) {
-      this.logger.error(`Failed to publish MCP server status ${mcpServerId} -> ${status}: ${publishError}`);
+      this.logger.error({ mcpServerId, status, err: publishError }, "Failed to publish MCP server status");
     }
   }
   async shutdown() {
@@ -152697,19 +152713,25 @@ var ToolService = class ToolService2 extends Service {
         this.logger.debug(`Processing MCP Servers update with ${msg.data.mcpServers.length} MCP Servers`);
         this.roots = msg.data.roots;
         const mcpServerIds = msg.data.mcpServers.map((mcpServer) => mcpServer.id);
-        const mcpServersToStop = Array.from(this.mcpServers.keys()).filter((mcpServerId) => !mcpServerIds.includes(mcpServerId));
-        for (const mcpServerId of mcpServersToStop) {
+        const runningToStop = Array.from(this.mcpServers.keys()).filter((id) => !mcpServerIds.includes(id));
+        const dormantToRemove = Array.from(this.dormantConfigs.keys()).filter((id) => !mcpServerIds.includes(id));
+        for (const mcpServerId of runningToStop) {
           const service = this.mcpServers.get(mcpServerId);
           await this.stopMCPServer({ id: mcpServerId, name: service.getName() });
         }
+        for (const mcpServerId of dormantToRemove) {
+          this.removeDormantServer(mcpServerId);
+        }
         for (const mcpServer of msg.data.mcpServers) {
-          await this.spawnMCPServer(mcpServer).catch(async (error48) => {
-            this.logger.error(`Failed to spawn MCP Server ${mcpServer.name}: ${error48}`);
+          await this.registerMCPServer(mcpServer).catch(async (error48) => {
+            this.logger.error({ mcpServerId: mcpServer.id, mcpServerName: mcpServer.name, err: error48 }, "Failed to register MCP Server");
+            this.publishMCPServerStatus(mcpServer.workspace?.id, mcpServer.id, "ERROR", error48 instanceof Error ? error48.message : String(error48));
             const service = this.mcpServers.get(mcpServer.id);
             if (service) {
               await this.stopService(service);
             }
             this.mcpServers.delete(mcpServer.id);
+            this.removeDormantServer(mcpServer.id);
           });
         }
       }
@@ -152737,6 +152759,13 @@ var ToolService = class ToolService2 extends Service {
       }
       this.cacheSubscriptions = [];
     }
+    if (this.startingServers.size > 0 || this.stoppingServers.size > 0) {
+      this.logger.debug({ starting: this.startingServers.size, stopping: this.stoppingServers.size }, "Waiting for in-flight MCP server activations/stops to settle");
+      await Promise.allSettled([
+        ...Array.from(this.startingServers.values()),
+        ...Array.from(this.stoppingServers.values())
+      ]);
+    }
     const serverIds = Array.from(this.mcpServers.keys());
     for (const mcpServerId of serverIds) {
       const service = this.mcpServers.get(mcpServerId);
@@ -152744,20 +152773,76 @@ var ToolService = class ToolService2 extends Service {
         continue;
       await this.stopMCPServer({ id: mcpServerId, name: service.getName() });
     }
+    for (const mcpServerId of Array.from(this.dormantConfigs.keys())) {
+      this.removeDormantServer(mcpServerId);
+    }
+    for (const timer of this.idleTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.idleTimers.clear();
   }
   /**
-   * Spawn an MCP Server
-   * - the mcpServer argument contains the list of tools and capabilities that the MCP Server advertises
+   * Register an MCP Server. For STDIO servers with lazy-start enabled, the server is registered
+   * as dormant (config stored, NATS tool subscriptions active, no subprocess spawned).
+   * For non-STDIO servers or when lazy-start is disabled, the server is activated immediately.
    */
-  async spawnMCPServer(mcpServer) {
+  async registerMCPServer(mcpServer) {
     const roots = this.getRoots();
-    const existingMcpServer = this.mcpServers.get(mcpServer.id);
-    if (existingMcpServer && getConfigSignature(existingMcpServer.getConfig(), existingMcpServer.getRoots()) === getConfigSignature(mcpServer, roots)) {
-      this.logger.debug(`MCPServer ${mcpServer.name} already running -> skipping spawn`);
-      const tools2 = mcpServer.tools ?? [];
-      this.ensureToolsSubscribed(mcpServer.id, tools2);
+    const newSignature = getConfigSignature(mcpServer, roots);
+    const existingRunning = this.mcpServers.get(mcpServer.id);
+    if (existingRunning && getConfigSignature(existingRunning.getConfig(), existingRunning.getRoots()) === newSignature) {
+      this.logger.debug(`MCPServer ${mcpServer.name} already running -> skipping`);
+      this.ensureToolsSubscribed(mcpServer.id, mcpServer.tools ?? []);
       return;
     }
+    const existingDormant = this.dormantConfigs.get(mcpServer.id);
+    if (existingDormant && existingDormant.configSignature === newSignature) {
+      this.logger.debug(`MCPServer ${mcpServer.name} already dormant with same config -> skipping`);
+      this.ensureToolsSubscribed(mcpServer.id, mcpServer.tools ?? []);
+      return;
+    }
+    if (existingRunning) {
+      this.logger.debug(`MCPServer ${mcpServer.name} config changed -> stopping`);
+      await this.stopMCPServer(mcpServer);
+    }
+    if (existingDormant) {
+      this.dormantConfigs.delete(mcpServer.id);
+    }
+    this.activationFailures.delete(mcpServer.id);
+    const isStdio = mcpServer.transport === dgraph_resolvers_types_exports.McpTransportType.Stdio;
+    const hasKnownTools = (mcpServer.tools?.length ?? 0) > 0;
+    if (this.lazyStartEnabled && isStdio && hasKnownTools) {
+      this.logger.info(`Registering MCPServer ${mcpServer.name} as dormant (lazy-start)`);
+      this.dormantConfigs.set(mcpServer.id, { config: mcpServer, configSignature: newSignature });
+      if (mcpServer.workspace?.id) {
+        this.mcpServerWorkspaces.set(mcpServer.id, mcpServer.workspace.id);
+      }
+      this.ensureToolsSubscribed(mcpServer.id, mcpServer.tools ?? []);
+      this.publishMCPServerStatus(mcpServer.workspace?.id, mcpServer.id, "IDLE");
+      return;
+    }
+    if (this.lazyStartEnabled && isStdio && !hasKnownTools) {
+      this.logger.info(`MCPServer ${mcpServer.name} has no known tools -> activating eagerly for tool discovery`);
+    }
+    await this.activateMCPServer(mcpServer);
+  }
+  /**
+   * Activate an MCP Server: spawn the subprocess, connect, and start observing tools.
+   * Can be called eagerly (from registerMCPServer) or on-demand (from ensureServerActive).
+   */
+  async activateMCPServer(mcpServerOrId) {
+    let mcpServer;
+    let isDormantActivation = false;
+    if (typeof mcpServerOrId === "string") {
+      const dormant = this.dormantConfigs.get(mcpServerOrId);
+      if (!dormant)
+        throw new Error(`No dormant config found for MCP Server ${mcpServerOrId}`);
+      mcpServer = dormant.config;
+      isDormantActivation = true;
+    } else {
+      mcpServer = mcpServerOrId;
+    }
+    const roots = this.getRoots();
     let authProvider;
     if (mcpServer.oauthProvider === "MCP_OAUTH") {
       const identity = this.authService.getIdentity();
@@ -152790,7 +152875,7 @@ var ToolService = class ToolService2 extends Service {
       }
     }
     const mcpServerService = this.toolServerServiceFactory(mcpServer, roots, authProvider);
-    this.logger.info(`Spawning MCPServer: ${mcpServer.name} with ${mcpServer.tools?.length ?? 0} tools, and roots: ${JSON.stringify(roots)}`);
+    this.logger.info(`Activating MCPServer: ${mcpServer.name} with ${mcpServer.tools?.length ?? 0} tools, and roots: ${JSON.stringify(roots)}`);
     if (this.mcpServers.has(mcpServer.id)) {
       this.logger.debug(`MCPServer ${mcpServer.name} already running -> shutting down`);
       await this.stopMCPServer(mcpServer);
@@ -152808,11 +152893,32 @@ var ToolService = class ToolService2 extends Service {
       this.mcpServerWorkspaces.delete(mcpServer.id);
       throw error48;
     }
+    if (isDormantActivation) {
+      this.dormantConfigs.delete(mcpServer.id);
+    }
     let hasPublishedConnected = false;
     mcpServerService.observeTools().subscribe({
       error: (err) => {
-        this.logger.error(`Tools observable error for MCP Server ${mcpServer.id}: ${err}`);
+        this.logger.error({ mcpServerId: mcpServer.id, err }, "Tools observable error for MCP Server");
         this.publishMCPServerStatus(mcpServer.workspace?.id, mcpServer.id, "ERROR", err instanceof Error ? err.message : String(err));
+        this.mcpServers.delete(mcpServer.id);
+        this.mcpTools.delete(mcpServer.id);
+        const idleTimer = this.idleTimers.get(mcpServer.id);
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          this.idleTimers.delete(mcpServer.id);
+        }
+        const stopPromise = this.stopService(mcpServerService).catch((stopErr) => this.logger.error({ mcpServerId: mcpServer.id, err: stopErr }, "Failed to stop errored MCP server")).then(() => {
+          this.stoppingServers.delete(mcpServer.id);
+          if (this.lazyStartEnabled && mcpServer.transport === dgraph_resolvers_types_exports.McpTransportType.Stdio) {
+            this.dormantConfigs.set(mcpServer.id, {
+              config: mcpServer,
+              configSignature: getConfigSignature(mcpServer, roots)
+            });
+            this.publishMCPServerStatus(mcpServer.workspace?.id, mcpServer.id, "IDLE");
+          }
+        });
+        this.stoppingServers.set(mcpServer.id, stopPromise);
       },
       next: (tools2) => {
         this.logger.debug(`Updating tools for MCP Server ${mcpServer.id} with ${tools2.length} tools`);
@@ -152833,13 +152939,119 @@ var ToolService = class ToolService2 extends Service {
           });
           this.natsService.publish(message);
         } catch (publishError) {
-          this.logger.warn(`Failed to publish discovered tools for ${mcpServer.id}: ${publishError}`);
+          this.logger.error({ mcpServerId: mcpServer.id, err: publishError }, "Failed to publish discovered tools \u2014 backend may show stale tool list");
         }
       }
     });
     const tools = mcpServer.tools ?? [];
     this.ensureToolsSubscribed(mcpServer.id, tools);
-    this.logger.info(`MCPServer ${mcpServer.name} spawned`);
+    if (this.lazyStartEnabled && mcpServer.transport === dgraph_resolvers_types_exports.McpTransportType.Stdio) {
+      this.resetIdleTimer(mcpServer.id);
+    }
+    this.logger.info(`MCPServer ${mcpServer.name} activated`);
+    return mcpServerService;
+  }
+  /**
+   * Ensure a dormant server is activated, deduplicating concurrent activation requests.
+   * Waits for any in-flight stop to complete before re-activating.
+   */
+  async ensureServerActive(mcpServerId) {
+    const existing = this.startingServers.get(mcpServerId);
+    if (existing)
+      return existing;
+    const stopping = this.stoppingServers.get(mcpServerId);
+    if (stopping) {
+      await stopping;
+    }
+    const promise2 = this.activateMCPServer(mcpServerId);
+    this.startingServers.set(mcpServerId, promise2);
+    try {
+      const service = await promise2;
+      if (!this.mcpServers.has(mcpServerId)) {
+        throw new Error(`MCP server ${mcpServerId} was deregistered during activation`);
+      }
+      return service;
+    } finally {
+      this.startingServers.delete(mcpServerId);
+    }
+  }
+  /**
+   * Reset the idle timer for a lazy-started server.
+   */
+  resetIdleTimer(mcpServerId) {
+    const existing = this.idleTimers.get(mcpServerId);
+    if (existing)
+      clearTimeout(existing);
+    const timer = setTimeout(() => {
+      this.idleShutdown(mcpServerId).catch((err) => this.logger.error({ mcpServerId, err }, "Idle shutdown failed"));
+    }, this.idleTimeoutMs);
+    this.idleTimers.set(mcpServerId, timer);
+  }
+  /**
+   * Shut down an idle MCP server and move it back to dormant state.
+   * NATS tool subscriptions and mcpTools are kept alive for on-demand re-activation.
+   */
+  async idleShutdown(mcpServerId) {
+    if (this.startingServers.has(mcpServerId)) {
+      this.resetIdleTimer(mcpServerId);
+      return;
+    }
+    const server = this.mcpServers.get(mcpServerId);
+    if (!server) {
+      this.logger.debug({ mcpServerId }, "Idle timer fired for server not in mcpServers map, ignoring");
+      this.idleTimers.delete(mcpServerId);
+      return;
+    }
+    const config2 = server.getConfig();
+    const roots = server.getRoots();
+    this.logger.info(`Idle shutdown for MCP server ${config2.name}`);
+    try {
+      await this.stopService(server);
+    } catch (err) {
+      this.logger.error({ mcpServerId, err }, "Error stopping service during idle shutdown");
+      this.mcpServers.delete(mcpServerId);
+      this.idleTimers.delete(mcpServerId);
+      this.dormantConfigs.set(mcpServerId, {
+        config: config2,
+        configSignature: getConfigSignature(config2, roots)
+      });
+      const workspaceId2 = this.mcpServerWorkspaces.get(mcpServerId);
+      this.publishMCPServerStatus(workspaceId2, mcpServerId, "IDLE");
+      return;
+    }
+    this.mcpServers.delete(mcpServerId);
+    this.dormantConfigs.set(mcpServerId, {
+      config: config2,
+      configSignature: getConfigSignature(config2, roots)
+    });
+    const workspaceId = this.mcpServerWorkspaces.get(mcpServerId);
+    this.publishMCPServerStatus(workspaceId, mcpServerId, "IDLE");
+    this.idleTimers.delete(mcpServerId);
+  }
+  /**
+   * Remove a dormant server completely: clean up NATS tool subscriptions, mcpTools, and config.
+   */
+  removeDormantServer(mcpServerId) {
+    this.dormantConfigs.delete(mcpServerId);
+    this.activationFailures.delete(mcpServerId);
+    const serverToolSubs = this.toolSubscriptions.get(mcpServerId);
+    if (serverToolSubs) {
+      for (const [toolId, subscription] of serverToolSubs.entries()) {
+        try {
+          subscription.unsubscribe();
+        } catch (error48) {
+          this.logger.warn({ toolId, err: error48 }, "Failed to unsubscribe dormant tool");
+        }
+      }
+      this.toolSubscriptions.delete(mcpServerId);
+    }
+    this.mcpTools.delete(mcpServerId);
+    this.mcpServerWorkspaces.delete(mcpServerId);
+    const timer = this.idleTimers.get(mcpServerId);
+    if (timer) {
+      clearTimeout(timer);
+      this.idleTimers.delete(mcpServerId);
+    }
   }
   // Subscribe to a tool and return the subscription
   subscribeToTool(tool2) {
@@ -152901,11 +153113,45 @@ var ToolService = class ToolService2 extends Service {
             continue;
           }
           this.logger.debug(`Found tool ${tool2.name} in MCP Server ${mcpServerId}`);
-          const mcpServer = this.mcpServers.get(mcpServerId);
+          let mcpServer = this.mcpServers.get(mcpServerId);
+          if (!mcpServer && this.dormantConfigs.has(mcpServerId)) {
+            const failures = this.activationFailures.get(mcpServerId);
+            if (failures && failures.count >= this.maxActivationRetries) {
+              const elapsed = Date.now() - failures.lastAttempt;
+              if (elapsed < this.activationCooldownMs) {
+                const retryInSec = Math.ceil((this.activationCooldownMs - elapsed) / 1e3);
+                msg.respond(new ErrorResponse({
+                  error: `MCP server failed to start after ${failures.count} attempts. Will retry in ${retryInSec}s.`
+                }));
+                toolCalled = true;
+                continue;
+              }
+              this.activationFailures.delete(mcpServerId);
+            }
+            this.logger.info(`Activating dormant MCP server ${mcpServerId} for tool call`);
+            try {
+              mcpServer = await this.ensureServerActive(mcpServerId);
+              this.activationFailures.delete(mcpServerId);
+            } catch (activationError) {
+              const prev = this.activationFailures.get(mcpServerId);
+              this.activationFailures.set(mcpServerId, {
+                count: (prev?.count ?? 0) + 1,
+                lastAttempt: Date.now()
+              });
+              this.logger.error({ mcpServerId, err: activationError }, "Failed to activate dormant MCP server");
+              const userMessage = activationError instanceof Error && activationError.message.includes("No dormant config") ? "MCP server is being reconfigured, please retry" : `MCP server activation failed: ${activationError instanceof Error ? activationError.message : String(activationError)}`;
+              msg.respond(new ErrorResponse({ error: userMessage }));
+              toolCalled = true;
+              continue;
+            }
+          }
           if (!mcpServer) {
             this.logger.warn(`MCP Server ${mcpServerId} not found`);
             continue;
           }
+          if (this.idleTimers.has(mcpServerId)) {
+            this.resetIdleTimer(mcpServerId);
+          }
           let _meta;
           const mcpServerConfig = mcpServer.getConfig();
           if (mcpServerConfig.oauthProvider && userId) {
@@ -153027,7 +153273,7 @@ var ToolService = class ToolService2 extends Service {
               executedBy
             }));
           } catch (callError) {
-            this.logger.error(`Tool call ${tool2.name} failed: ${callError}`);
+            this.logger.error({ mcpServerId, toolName: tool2.name, err: callError }, "Tool call failed");
             msg.respond(new ErrorResponse({
               error: `Tool call failed: ${callError instanceof Error ? callError.message : String(callError)}`
             }));
@@ -153049,7 +153295,8 @@ var ToolService = class ToolService2 extends Service {
    */
   async handleScriptExecution(msg, executedBy) {
     const { scriptId, scriptName, workspaceId, arguments: toolArgs } = msg.data;
-    const args = toolArgs?.args || [];
+    const rawArgs = toolArgs?.args;
+    const args = Array.isArray(rawArgs) ? rawArgs : typeof rawArgs === "string" && rawArgs.trim() ? parseScriptArgs(rawArgs) : [];
     this.logger.info({ scriptId, scriptName, argsCount: args.length }, "Handling script execution request");
     const fetchRequest = SkillFetchScriptRequest.create({
       scriptId,
@@ -153313,6 +153560,11 @@ ${errorOutput}`;
       await this.stopService(service);
     }
     this.mcpServers.delete(mcpServer.id);
+    const idleTimer = this.idleTimers.get(mcpServer.id);
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      this.idleTimers.delete(mcpServer.id);
+    }
     const workspaceId = this.mcpServerWorkspaces.get(mcpServer.id);
     this.publishMCPServerStatus(workspaceId, mcpServer.id, "DISCONNECTED");
     this.mcpServerWorkspaces.delete(mcpServer.id);