@dexto/agent-management 1.5.2 → 1.5.4

package/dist/tool-provider/runtime-service.cjs

@@ -0,0 +1,390 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var runtime_service_exports = {};
+__export(runtime_service_exports, {
+  RuntimeService: () => RuntimeService
+});
+module.exports = __toCommonJS(runtime_service_exports);
+var import_AgentRuntime = require("../runtime/AgentRuntime.js");
+var import_approval_delegation = require("../runtime/approval-delegation.js");
+var import_loader = require("../config/loader.js");
+var import_registry = require("../registry/registry.js");
+class RuntimeService {
+  runtime;
+  parentId;
+  parentAgent;
+  config;
+  logger;
+  constructor(parentAgent, config, logger) {
+    this.parentAgent = parentAgent;
+    this.config = config;
+    this.logger = logger;
+    this.parentId = parentAgent.config.agentId ?? `parent-${Date.now()}`;
+    this.runtime = new import_AgentRuntime.AgentRuntime({
+      config: {
+        maxAgents: config.maxConcurrentAgents,
+        defaultTaskTimeout: config.defaultTimeout
+      },
+      logger
+    });
+    this.logger.debug(
+      `RuntimeService initialized for parent '${this.parentId}' (maxAgents: ${config.maxConcurrentAgents})`
+    );
+  }
+  /**
+   * Get count of sub-agents belonging to this parent
+   */
+  getSubAgentCount() {
+    return this.runtime.listAgents({ group: this.parentId }).length;
+  }
+  /**
+   * Check if this parent can spawn another sub-agent
+   */
+  canSpawn() {
+    return this.getSubAgentCount() < this.config.maxConcurrentAgents;
+  }
+  /**
+   * Spawn a sub-agent and execute a task
+   *
+   * This is the main method for the spawn_agent tool.
+   * It creates a sub-agent, executes the task, and cleans up after completion.
+   * If the sub-agent's LLM config fails, automatically falls back to parent's LLM.
+   *
+   * @param input.task - Short task description (for logging/UI)
+   * @param input.instructions - Full prompt sent to sub-agent
+   * @param input.agentId - Optional agent ID from registry
+   * @param input.timeout - Optional task timeout in milliseconds
+   * @param input.toolCallId - Optional tool call ID for progress events
+   * @param input.sessionId - Optional session ID for progress events
+   */
+  async spawnAndExecute(input) {
+    if (!this.config.allowSpawning) {
+      return {
+        success: false,
+        error: "Agent spawning is disabled in configuration"
+      };
+    }
+    if (!this.canSpawn()) {
+      return {
+        success: false,
+        error: `Maximum sub-agents limit (${this.config.maxConcurrentAgents}) reached for this parent`
+      };
+    }
+    if (input.agentId && this.config.allowedAgents) {
+      if (!this.config.allowedAgents.includes(input.agentId)) {
+        return {
+          success: false,
+          error: `Agent '${input.agentId}' is not in the allowed agents list. Allowed: ${this.config.allowedAgents.join(", ")}`
+        };
+      }
+    }
+    const timeout = input.timeout ?? this.config.defaultTimeout;
+    let autoApprove = false;
+    if (input.agentId && this.config.autoApproveAgents) {
+      autoApprove = this.config.autoApproveAgents.includes(input.agentId);
+    }
+    const result = await this.trySpawnWithFallback(
+      input,
+      timeout,
+      autoApprove,
+      input.toolCallId,
+      input.sessionId
+    );
+    return result;
+  }
+  /**
+   * Set up progress event emission for a sub-agent.
+   * Subscribes to llm:tool-call and llm:response events and emits service:event with progress data.
+   *
+   * @returns Cleanup function to unsubscribe from events
+   */
+  setupProgressTracking(subAgentHandle, input, toolCallId, sessionId) {
+    if (!toolCallId || !sessionId) {
+      this.logger.debug(
+        `[Progress] Skipping progress tracking - missing toolCallId (${toolCallId}) or sessionId (${sessionId})`
+      );
+      return () => {
+      };
+    }
+    this.logger.debug(
+      `[Progress] Setting up progress tracking for sub-agent ${subAgentHandle.agentId} (toolCallId: ${toolCallId}, sessionId: ${sessionId})`
+    );
+    let toolCount = 0;
+    const tokenUsage = { input: 0, output: 0, total: 0 };
+    let currentTool = "";
+    const subAgentBus = subAgentHandle.agent.agentEventBus;
+    const parentBus = this.parentAgent.agentEventBus;
+    const emitProgress = (tool, args) => {
+      parentBus.emit("service:event", {
+        service: "agent-spawner",
+        event: "progress",
+        toolCallId,
+        sessionId,
+        data: {
+          task: input.task,
+          agentId: input.agentId ?? "default",
+          toolsCalled: toolCount,
+          currentTool: tool,
+          currentArgs: args,
+          tokenUsage: { ...tokenUsage }
+        }
+      });
+    };
+    const toolCallHandler = (event) => {
+      toolCount++;
+      let displayToolName = event.toolName;
+      if (displayToolName.startsWith("internal--")) {
+        displayToolName = displayToolName.replace("internal--", "");
+      } else if (displayToolName.startsWith("custom--")) {
+        displayToolName = displayToolName.replace("custom--", "");
+      } else if (displayToolName.startsWith("mcp--")) {
+        const parts = displayToolName.split("--");
+        if (parts.length >= 3) {
+          displayToolName = parts.slice(2).join("--");
+        }
+      }
+      currentTool = displayToolName;
+      this.logger.debug(
+        `[Progress] Sub-agent tool call #${toolCount}: ${displayToolName} (toolCallId: ${toolCallId})`
+      );
+      emitProgress(displayToolName, event.args);
+    };
+    const responseHandler = (event) => {
+      if (event.tokenUsage) {
+        tokenUsage.input = event.tokenUsage.inputTokens ?? 0;
+        tokenUsage.output += event.tokenUsage.outputTokens ?? 0;
+        tokenUsage.total = tokenUsage.input + tokenUsage.output;
+        this.logger.debug(
+          `[Progress] Sub-agent tokens: input=${tokenUsage.input}, cumOutput=${tokenUsage.output}, total=${tokenUsage.total}`
+        );
+        emitProgress(currentTool || "processing");
+      }
+    };
+    subAgentBus.on("llm:tool-call", toolCallHandler);
+    subAgentBus.on("llm:response", responseHandler);
+    return () => {
+      subAgentBus.off("llm:tool-call", toolCallHandler);
+      subAgentBus.off("llm:response", responseHandler);
+    };
+  }
+  /**
+   * Try to spawn agent, falling back to parent's LLM config if the sub-agent's config fails
+   */
+  async trySpawnWithFallback(input, timeout, autoApprove, toolCallId, sessionId) {
+    let spawnedAgentId;
+    let usedFallback = false;
+    let cleanupProgressTracking;
+    try {
+      const buildOptions = {};
+      if (input.agentId !== void 0) {
+        buildOptions.agentId = input.agentId;
+      }
+      if (autoApprove) {
+        buildOptions.autoApprove = autoApprove;
+      }
+      let subAgentConfig = await this.buildSubAgentConfig(buildOptions);
+      let handle;
+      try {
+        handle = await this.runtime.spawnAgent({
+          agentConfig: subAgentConfig,
+          ephemeral: true,
+          group: this.parentId,
+          metadata: {
+            parentId: this.parentId,
+            task: input.task,
+            autoApprove,
+            spawnedAt: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          onBeforeStart: (agent) => {
+            if (!autoApprove) {
+              const delegatingHandler = (0, import_approval_delegation.createDelegatingApprovalHandler)(
+                this.parentAgent.services.approvalManager,
+                agent.config.agentId ?? "unknown",
+                this.logger
+              );
+              agent.setApprovalHandler(delegatingHandler);
+            }
+          }
+        });
+        spawnedAgentId = handle.agentId;
+      } catch (spawnError) {
+        const errorMsg = spawnError instanceof Error ? spawnError.message : String(spawnError);
+        const isLlmError = errorMsg.includes("Model") || errorMsg.includes("model") || errorMsg.includes("API") || errorMsg.includes("apiKey") || errorMsg.includes("provider");
+        if (isLlmError && input.agentId) {
+          this.logger.warn(
+            `Sub-agent LLM config failed: ${errorMsg}. Falling back to parent's LLM config.`
+          );
+          usedFallback = true;
+          buildOptions.inheritLlm = true;
+          subAgentConfig = await this.buildSubAgentConfig(buildOptions);
+          handle = await this.runtime.spawnAgent({
+            agentConfig: subAgentConfig,
+            ephemeral: true,
+            group: this.parentId,
+            metadata: {
+              parentId: this.parentId,
+              task: input.task,
+              autoApprove,
+              usedLlmFallback: true,
+              spawnedAt: (/* @__PURE__ */ new Date()).toISOString()
+            },
+            onBeforeStart: (agent) => {
+              if (!autoApprove) {
+                const delegatingHandler = (0, import_approval_delegation.createDelegatingApprovalHandler)(
+                  this.parentAgent.services.approvalManager,
+                  agent.config.agentId ?? "unknown",
+                  this.logger
+                );
+                agent.setApprovalHandler(delegatingHandler);
+              }
+            }
+          });
+          spawnedAgentId = handle.agentId;
+        } else {
+          throw spawnError;
+        }
+      }
+      this.logger.info(
+        `Spawned sub-agent '${spawnedAgentId}' for task: ${input.task}${autoApprove ? " (auto-approve)" : ""}${usedFallback ? " (using parent LLM)" : ""}`
+      );
+      cleanupProgressTracking = this.setupProgressTracking(
+        handle,
+        input,
+        toolCallId,
+        sessionId
+      );
+      const result = await this.runtime.executeTask(
+        spawnedAgentId,
+        input.instructions,
+        timeout
+      );
+      const output = {
+        success: result.success
+      };
+      if (result.response !== void 0) {
+        output.response = result.response;
+      }
+      if (result.error !== void 0) {
+        output.error = result.error;
+      }
+      return output;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Failed to spawn and execute: ${errorMessage}`);
+      return {
+        success: false,
+        error: errorMessage
+      };
+    } finally {
+      if (cleanupProgressTracking) {
+        cleanupProgressTracking();
+      }
+      if (spawnedAgentId) {
+        try {
+          await this.runtime.stopAgent(spawnedAgentId);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Build sub-agent config based on registry agent ID or parent config
+   *
+   * @param options.agentId - Agent ID from registry
+   * @param options.inheritLlm - Use parent's LLM config instead of sub-agent's
+   * @param options.autoApprove - Auto-approve all tool calls
+   */
+  async buildSubAgentConfig(options) {
+    const { agentId, inheritLlm, autoApprove } = options;
+    const parentConfig = this.parentAgent.config;
+    const toolConfirmationMode = autoApprove ? "auto-approve" : "manual";
+    if (agentId) {
+      const registry = (0, import_registry.getAgentRegistry)();
+      if (!registry.hasAgent(agentId)) {
+        this.logger.warn(`Agent '${agentId}' not found in registry. Using default config.`);
+      } else {
+        const configPath = await registry.resolveAgent(agentId);
+        this.logger.debug(`Loading agent config from registry: ${configPath}`);
+        const loadedConfig = await (0, import_loader.loadAgentConfig)(configPath, this.logger);
+        let llmConfig = loadedConfig.llm;
+        if (inheritLlm) {
+          this.logger.debug("Using parent LLM config (inheritLlm=true)");
+          llmConfig = { ...parentConfig.llm };
+        }
+        return {
+          ...loadedConfig,
+          llm: llmConfig,
+          toolConfirmation: {
+            ...loadedConfig.toolConfirmation,
+            mode: toolConfirmationMode
+          },
+          // Suppress sub-agent console logs entirely using silent transport
+          logger: {
+            level: "error",
+            transports: [{ type: "silent" }]
+          }
+        };
+      }
+    }
+    const config = {
+      llm: { ...parentConfig.llm },
+      // Default system prompt for sub-agents
+      systemPrompt: "You are a helpful sub-agent. Complete the task given to you efficiently and concisely.",
+      toolConfirmation: {
+        mode: toolConfirmationMode
+      },
+      // Suppress sub-agent console logs entirely using silent transport
+      logger: {
+        level: "error",
+        transports: [{ type: "silent" }]
+      }
+    };
+    return config;
+  }
+  /**
+   * Get information about available agents for tool description.
+   * Returns agent metadata from registry, filtered by allowedAgents if configured.
+   */
+  getAvailableAgents() {
+    const registry = (0, import_registry.getAgentRegistry)();
+    const allAgents = registry.getAvailableAgents();
+    if (this.config.allowedAgents && this.config.allowedAgents.length > 0) {
+      const result = [];
+      for (const id of this.config.allowedAgents) {
+        const agent = allAgents[id];
+        if (agent) {
+          result.push(agent);
+        }
+      }
+      return result;
+    }
+    return Object.values(allAgents);
+  }
+  /**
+   * Clean up all sub-agents (called when parent stops)
+   */
+  async cleanup() {
+    this.logger.debug(`Cleaning up RuntimeService for parent '${this.parentId}'`);
+    await this.runtime.stopAll({ group: this.parentId });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RuntimeService
+});

package/dist/tool-provider/runtime-service.d.ts

@@ -0,0 +1,83 @@
+/**
+ * RuntimeService - Bridge between tools and AgentRuntime
+ *
+ * Manages the relationship between a parent agent and its sub-agents,
+ * providing methods that tools can call to spawn and execute tasks.
+ *
+ * This service adds parent-child semantics on top of the general-purpose AgentRuntime:
+ * - Uses `group` to associate spawned agents with the parent
+ * - Wires up approval delegation so sub-agent tool requests go to parent
+ * - Enforces per-parent agent limits
+ * - Always cleans up agents after task completion (synchronous model)
+ */
+import type { DextoAgent, IDextoLogger } from '@dexto/core';
+import type { AgentRegistryEntry } from '../registry/types.js';
+import type { AgentSpawnerConfig } from './schemas.js';
+import type { SpawnAgentOutput } from './types.js';
+export declare class RuntimeService {
+    private runtime;
+    private parentId;
+    private parentAgent;
+    private config;
+    private logger;
+    constructor(parentAgent: DextoAgent, config: AgentSpawnerConfig, logger: IDextoLogger);
+    /**
+     * Get count of sub-agents belonging to this parent
+     */
+    private getSubAgentCount;
+    /**
+     * Check if this parent can spawn another sub-agent
+     */
+    private canSpawn;
+    /**
+     * Spawn a sub-agent and execute a task
+     *
+     * This is the main method for the spawn_agent tool.
+     * It creates a sub-agent, executes the task, and cleans up after completion.
+     * If the sub-agent's LLM config fails, automatically falls back to parent's LLM.
+     *
+     * @param input.task - Short task description (for logging/UI)
+     * @param input.instructions - Full prompt sent to sub-agent
+     * @param input.agentId - Optional agent ID from registry
+     * @param input.timeout - Optional task timeout in milliseconds
+     * @param input.toolCallId - Optional tool call ID for progress events
+     * @param input.sessionId - Optional session ID for progress events
+     */
+    spawnAndExecute(input: {
+        task: string;
+        instructions: string;
+        agentId?: string;
+        timeout?: number;
+        toolCallId?: string;
+        sessionId?: string;
+    }): Promise<SpawnAgentOutput>;
+    /**
+     * Set up progress event emission for a sub-agent.
+     * Subscribes to llm:tool-call and llm:response events and emits service:event with progress data.
+     *
+     * @returns Cleanup function to unsubscribe from events
+     */
+    private setupProgressTracking;
+    /**
+     * Try to spawn agent, falling back to parent's LLM config if the sub-agent's config fails
+     */
+    private trySpawnWithFallback;
+    /**
+     * Build sub-agent config based on registry agent ID or parent config
+     *
+     * @param options.agentId - Agent ID from registry
+     * @param options.inheritLlm - Use parent's LLM config instead of sub-agent's
+     * @param options.autoApprove - Auto-approve all tool calls
+     */
+    private buildSubAgentConfig;
+    /**
+     * Get information about available agents for tool description.
+     * Returns agent metadata from registry, filtered by allowedAgents if configured.
+     */
+    getAvailableAgents(): AgentRegistryEntry[];
+    /**
+     * Clean up all sub-agents (called when parent stops)
+     */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=runtime-service.d.ts.map

package/dist/tool-provider/runtime-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-service.d.ts","sourceRoot":"","sources":["../../src/tool-provider/runtime-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AAKzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,qBAAa,cAAc;IACvB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAe;gBAEjB,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,YAAY;IAuBrF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,KAAK,EAAE;QACzB,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8C7B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAiH7B;;OAEG;YACW,oBAAoB;IAgKlC;;;;;;OAMG;YACW,mBAAmB;IAuEjC;;;OAGG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAoB1C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAIjC"}