@dexto/agent-management 1.5.1 → 1.5.3

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

@@ -0,0 +1,346 @@
+import { AgentRuntime } from "../runtime/AgentRuntime.js";
+import { createDelegatingApprovalHandler } from "../runtime/approval-delegation.js";
+import { loadAgentConfig } from "../config/loader.js";
+import { getAgentRegistry } from "../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 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 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 subAgentBus = subAgentHandle.agent.agentEventBus;
+    const parentBus = this.parentAgent.agentEventBus;
+    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("--");
+        }
+      }
+      this.logger.debug(
+        `[Progress] Sub-agent tool call #${toolCount}: ${displayToolName} (toolCallId: ${toolCallId})`
+      );
+      parentBus.emit("service:event", {
+        service: "agent-spawner",
+        event: "progress",
+        toolCallId,
+        sessionId,
+        data: {
+          task: input.task,
+          agentId: input.agentId ?? "default",
+          toolsCalled: toolCount,
+          currentTool: displayToolName,
+          currentArgs: event.args
+        }
+      });
+    };
+    subAgentBus.on("llm:tool-call", toolCallHandler);
+    return () => {
+      subAgentBus.off("llm:tool-call", toolCallHandler);
+    };
+  }
+  /**
+   * 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 = 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 = 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 = 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 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 = 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 });
+  }
+}
+export {
+  RuntimeService
+};

package/dist/tool-provider/schemas.cjs

@@ -0,0 +1,73 @@
+"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 schemas_exports = {};
+__export(schemas_exports, {
+  AgentSpawnerConfigSchema: () => AgentSpawnerConfigSchema,
+  SpawnAgentInputSchema: () => SpawnAgentInputSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+const AgentSpawnerConfigSchema = import_zod.z.object({
+  /** Type discriminator for the provider */
+  type: import_zod.z.literal("agent-spawner"),
+  /** Maximum concurrent sub-agents this parent can spawn (default: 5) */
+  maxConcurrentAgents: import_zod.z.number().int().positive().default(5).describe("Maximum concurrent sub-agents"),
+  /** Default timeout for task execution in milliseconds (default: 300000 = 5 min) */
+  defaultTimeout: import_zod.z.number().int().positive().default(3e5).describe("Default task timeout in milliseconds"),
+  /** Whether spawning is enabled (default: true) */
+  allowSpawning: import_zod.z.boolean().default(true).describe("Whether agent spawning is enabled"),
+  /**
+   * List of agent IDs from the registry that this parent can spawn.
+   * If not provided, any registry agent can be spawned.
+   *
+   * Example:
+   * ```yaml
+   * customTools:
+   *   - type: agent-spawner
+   *     allowedAgents: ["explore-agent", "research-agent"]
+   * ```
+   */
+  allowedAgents: import_zod.z.array(import_zod.z.string().min(1)).optional().describe("Agent IDs from registry that can be spawned (omit to allow all)"),
+  /**
+   * Agent IDs that should have their tools auto-approved.
+   * Use for agents with only read-only/safe tools (e.g., explore-agent).
+   *
+   * Example:
+   * ```yaml
+   * customTools:
+   *   - type: agent-spawner
+   *     allowedAgents: ["explore-agent"]
+   *     autoApproveAgents: ["explore-agent"]
+   * ```
+   */
+  autoApproveAgents: import_zod.z.array(import_zod.z.string().min(1)).optional().describe("Agent IDs that should have tools auto-approved (read-only agents)")
+}).strict().describe("Configuration for the agent spawner tool provider");
+const SpawnAgentInputSchema = import_zod.z.object({
+  /** Short task description (shown in UI/logs) */
+  task: import_zod.z.string().min(1).describe("Short task description for UI/logs"),
+  /** Detailed instructions for the sub-agent */
+  instructions: import_zod.z.string().min(1).describe("Detailed instructions for the sub-agent to execute"),
+  /** Agent ID from registry (optional - uses default minimal agent if not provided) */
+  agentId: import_zod.z.string().min(1).optional().describe("Agent ID from registry")
+}).strict();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentSpawnerConfigSchema,
+  SpawnAgentInputSchema
+});

package/dist/tool-provider/schemas.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Agent Spawner Tool Provider Schemas
+ *
+ * Zod schemas for the agent spawner tool provider configuration and inputs.
+ */
+import { z } from 'zod';
+/**
+ * Configuration schema for the agent spawner tool provider
+ */
+export declare const AgentSpawnerConfigSchema: z.ZodObject<{
+    /** Type discriminator for the provider */
+    type: z.ZodLiteral<"agent-spawner">;
+    /** Maximum concurrent sub-agents this parent can spawn (default: 5) */
+    maxConcurrentAgents: z.ZodDefault<z.ZodNumber>;
+    /** Default timeout for task execution in milliseconds (default: 300000 = 5 min) */
+    defaultTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Whether spawning is enabled (default: true) */
+    allowSpawning: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * List of agent IDs from the registry that this parent can spawn.
+     * If not provided, any registry agent can be spawned.
+     *
+     * Example:
+     * ```yaml
+     * customTools:
+     *   - type: agent-spawner
+     *     allowedAgents: ["explore-agent", "research-agent"]
+     * ```
+     */
+    allowedAgents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Agent IDs that should have their tools auto-approved.
+     * Use for agents with only read-only/safe tools (e.g., explore-agent).
+     *
+     * Example:
+     * ```yaml
+     * customTools:
+     *   - type: agent-spawner
+     *     allowedAgents: ["explore-agent"]
+     *     autoApproveAgents: ["explore-agent"]
+     * ```
+     */
+    autoApproveAgents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    type: "agent-spawner";
+    maxConcurrentAgents: number;
+    defaultTimeout: number;
+    allowSpawning: boolean;
+    allowedAgents?: string[] | undefined;
+    autoApproveAgents?: string[] | undefined;
+}, {
+    type: "agent-spawner";
+    maxConcurrentAgents?: number | undefined;
+    defaultTimeout?: number | undefined;
+    allowSpawning?: boolean | undefined;
+    allowedAgents?: string[] | undefined;
+    autoApproveAgents?: string[] | undefined;
+}>;
+export type AgentSpawnerConfig = z.output<typeof AgentSpawnerConfigSchema>;
+/**
+ * Input schema for spawn_agent tool
+ *
+ * Note: Timeout is configured at the provider level (defaultTimeout in config).
+ * We don't expose timeout as a tool parameter because lowering it just wastes runs.
+ */
+export declare const SpawnAgentInputSchema: z.ZodObject<{
+    /** Short task description (shown in UI/logs) */
+    task: z.ZodString;
+    /** Detailed instructions for the sub-agent */
+    instructions: z.ZodString;
+    /** Agent ID from registry (optional - uses default minimal agent if not provided) */
+    agentId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    task: string;
+    instructions: string;
+    agentId?: string | undefined;
+}, {
+    task: string;
+    instructions: string;
+    agentId?: string | undefined;
+}>;
+export type SpawnAgentInput = z.output<typeof SpawnAgentInputSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tool-provider/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/tool-provider/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,wBAAwB;IAE7B,0CAA0C;;IAG1C,uEAAuE;;IAQvE,mFAAmF;;IAQnF,kDAAkD;;IAGlD;;;;;;;;;;OAUG;;IAMH;;;;;;;;;;;OAWG;;;;;;;;;;;;;;;;EAOuD,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM3E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;IAE1B,gDAAgD;;IAGhD,8CAA8C;;IAM9C,qFAAqF;;;;;;;;;;EAGhF,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/tool-provider/schemas.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+const AgentSpawnerConfigSchema = z.object({
+  /** Type discriminator for the provider */
+  type: z.literal("agent-spawner"),
+  /** Maximum concurrent sub-agents this parent can spawn (default: 5) */
+  maxConcurrentAgents: z.number().int().positive().default(5).describe("Maximum concurrent sub-agents"),
+  /** Default timeout for task execution in milliseconds (default: 300000 = 5 min) */
+  defaultTimeout: z.number().int().positive().default(3e5).describe("Default task timeout in milliseconds"),
+  /** Whether spawning is enabled (default: true) */
+  allowSpawning: z.boolean().default(true).describe("Whether agent spawning is enabled"),
+  /**
+   * List of agent IDs from the registry that this parent can spawn.
+   * If not provided, any registry agent can be spawned.
+   *
+   * Example:
+   * ```yaml
+   * customTools:
+   *   - type: agent-spawner
+   *     allowedAgents: ["explore-agent", "research-agent"]
+   * ```
+   */
+  allowedAgents: z.array(z.string().min(1)).optional().describe("Agent IDs from registry that can be spawned (omit to allow all)"),
+  /**
+   * Agent IDs that should have their tools auto-approved.
+   * Use for agents with only read-only/safe tools (e.g., explore-agent).
+   *
+   * Example:
+   * ```yaml
+   * customTools:
+   *   - type: agent-spawner
+   *     allowedAgents: ["explore-agent"]
+   *     autoApproveAgents: ["explore-agent"]
+   * ```
+   */
+  autoApproveAgents: z.array(z.string().min(1)).optional().describe("Agent IDs that should have tools auto-approved (read-only agents)")
+}).strict().describe("Configuration for the agent spawner tool provider");
+const SpawnAgentInputSchema = z.object({
+  /** Short task description (shown in UI/logs) */
+  task: z.string().min(1).describe("Short task description for UI/logs"),
+  /** Detailed instructions for the sub-agent */
+  instructions: z.string().min(1).describe("Detailed instructions for the sub-agent to execute"),
+  /** Agent ID from registry (optional - uses default minimal agent if not provided) */
+  agentId: z.string().min(1).optional().describe("Agent ID from registry")
+}).strict();
+export {
+  AgentSpawnerConfigSchema,
+  SpawnAgentInputSchema
+};

package/dist/tool-provider/spawn-agent-tool.cjs

@@ -0,0 +1,89 @@
+"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 spawn_agent_tool_exports = {};
+__export(spawn_agent_tool_exports, {
+  createSpawnAgentTool: () => createSpawnAgentTool
+});
+module.exports = __toCommonJS(spawn_agent_tool_exports);
+var import_schemas = require("./schemas.js");
+function buildDescription(service) {
+  const availableAgents = service.getAvailableAgents();
+  if (availableAgents.length === 0) {
+    return `Spawn a sub-agent to handle a specific task. The sub-agent executes the task and returns the result.
+
+No specialized agents are configured. The sub-agent will inherit your LLM with a minimal config.
+
+## Parameters
+- **task**: Short description for UI/logs (e.g., "Search for authentication code")
+- **instructions**: Detailed instructions for the sub-agent`;
+  }
+  const agentsList = availableAgents.map((agent) => {
+    const tags = agent.tags?.length ? ` [${agent.tags.slice(0, 3).join(", ")}]` : "";
+    return `### ${agent.id}
+${agent.description}${tags}`;
+  }).join("\n\n");
+  return `Spawn a specialized sub-agent to handle a task. The sub-agent executes independently and returns the result.
+
+## Available Agents
+
+${agentsList}
+
+## Parameters
+- **task**: Short description for UI/logs (e.g., "Explore authentication flow")
+- **instructions**: Detailed instructions sent to the sub-agent
+- **agentId**: Agent ID from the list above (e.g., "${availableAgents[0]?.id ?? "explore-agent"}")
+
+## Notes
+- Sub-agents have their own tools, LLM, and conversation context
+- Read-only agents (like explore-agent) have auto-approved tool calls for speed
+- If a sub-agent's LLM fails, it automatically falls back to your LLM`;
+}
+function createSpawnAgentTool(service) {
+  return {
+    id: "spawn_agent",
+    description: buildDescription(service),
+    inputSchema: import_schemas.SpawnAgentInputSchema,
+    execute: async (input, context) => {
+      const validatedInput = input;
+      const options = {
+        task: validatedInput.task,
+        instructions: validatedInput.instructions
+      };
+      if (validatedInput.agentId !== void 0) {
+        options.agentId = validatedInput.agentId;
+      }
+      if (context?.toolCallId !== void 0) {
+        options.toolCallId = context.toolCallId;
+      }
+      if (context?.sessionId !== void 0) {
+        options.sessionId = context.sessionId;
+      }
+      const result = await service.spawnAndExecute(options);
+      if (result.success) {
+        return result.response ?? "Task completed successfully.";
+      } else {
+        return `Error: ${result.error ?? "Unknown error"}`;
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSpawnAgentTool
+});

package/dist/tool-provider/spawn-agent-tool.d.ts

@@ -0,0 +1,10 @@
+/**
+ * spawn_agent Tool
+ *
+ * Spawns a sub-agent to handle a specific task.
+ * The sub-agent will execute the task and return the result.
+ */
+import type { InternalTool } from '@dexto/core';
+import type { RuntimeService } from './runtime-service.js';
+export declare function createSpawnAgentTool(service: RuntimeService): InternalTool;
+//# sourceMappingURL=spawn-agent-tool.d.ts.map

package/dist/tool-provider/spawn-agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agent-tool.d.ts","sourceRoot":"","sources":["../../src/tool-provider/spawn-agent-tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAwB,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA4C3D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CA0C1E"}