@dexto/orchestration 1.5.8

package/dist/tools/start-task.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { OrchestrationTool } from './types.js';
+import '../task-registry.js';
+import '../types.js';
+import '../signal-bus.js';
+import '../condition-engine.js';
+
+/**
+ * start_task Tool
+ *
+ * Starts a background task without blocking.
+ * This is a higher-level tool that delegates to task-specific providers.
+ */
+
+/**
+ * Input schema for start_task tool
+ */
+declare const StartTaskInputSchema: z.ZodEffects<z.ZodObject<{
+    /** Task type to start */
+    type: z.ZodEnum<["agent", "process", "generic"]>;
+    /** Task description for agent (required for type='agent') */
+    task: z.ZodOptional<z.ZodString>;
+    /** Custom system prompt for agent */
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    /** Command to run (required for type='process') */
+    command: z.ZodOptional<z.ZodString>;
+    /** Description for generic task */
+    description: z.ZodOptional<z.ZodString>;
+    /** Timeout in milliseconds */
+    timeout: z.ZodOptional<z.ZodNumber>;
+    /** Auto-notify when complete (triggers agent turn) */
+    notify: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    type: "agent" | "process" | "generic";
+    notify: boolean;
+    timeout?: number | undefined;
+    task?: string | undefined;
+    command?: string | undefined;
+    description?: string | undefined;
+    systemPrompt?: string | undefined;
+}, {
+    type: "agent" | "process" | "generic";
+    timeout?: number | undefined;
+    task?: string | undefined;
+    command?: string | undefined;
+    description?: string | undefined;
+    systemPrompt?: string | undefined;
+    notify?: boolean | undefined;
+}>, {
+    type: "agent" | "process" | "generic";
+    notify: boolean;
+    timeout?: number | undefined;
+    task?: string | undefined;
+    command?: string | undefined;
+    description?: string | undefined;
+    systemPrompt?: string | undefined;
+}, {
+    type: "agent" | "process" | "generic";
+    timeout?: number | undefined;
+    task?: string | undefined;
+    command?: string | undefined;
+    description?: string | undefined;
+    systemPrompt?: string | undefined;
+    notify?: boolean | undefined;
+}>;
+type StartTaskInput = z.infer<typeof StartTaskInputSchema>;
+/**
+ * Output from start_task tool
+ */
+interface StartTaskOutput {
+    /** Whether task was started successfully */
+    success: boolean;
+    /** Task ID for tracking */
+    taskId?: string;
+    /** Error message if failed to start */
+    error?: string;
+    /** Status */
+    status?: 'running';
+}
+/**
+ * Task starter interface - implemented by agent-spawner, process-tools, etc.
+ */
+interface TaskStarter {
+    /** Start a task and return the promise */
+    start(input: StartTaskInput): Promise<{
+        taskId: string;
+        promise: Promise<unknown>;
+    }>;
+}
+/**
+ * Create the start_task tool
+ *
+ * Note: This tool requires task starters to be registered for each task type.
+ * Use `registerTaskStarter` to add support for agent/process/generic tasks.
+ */
+declare function createStartTaskTool(starters: Map<string, TaskStarter>): OrchestrationTool;
+/**
+ * Create a simple generic task starter for testing
+ */
+declare function createGenericTaskStarter(): TaskStarter;
+
+export { type StartTaskInput, StartTaskInputSchema, type StartTaskOutput, type TaskStarter, createGenericTaskStarter, createStartTaskTool };

package/dist/tools/start-task.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+const StartTaskInputSchema = z.object({
+  /** Task type to start */
+  type: z.enum(["agent", "process", "generic"]).describe("Type of task to start"),
+  // Agent task options
+  /** Task description for agent (required for type='agent') */
+  task: z.string().optional().describe("Task description for agent execution"),
+  /** Custom system prompt for agent */
+  systemPrompt: z.string().optional().describe("Custom system prompt for the agent"),
+  // Process task options
+  /** Command to run (required for type='process') */
+  command: z.string().optional().describe("Shell command to execute"),
+  // Generic task options
+  /** Description for generic task */
+  description: z.string().optional().describe("Description of the task"),
+  // Common options
+  /** Timeout in milliseconds */
+  timeout: z.number().positive().optional().describe("Task timeout in milliseconds"),
+  /** Auto-notify when complete (triggers agent turn) */
+  notify: z.boolean().default(false).describe("Auto-notify when task completes")
+}).strict().superRefine((data, ctx) => {
+  if (data.type === "agent" && !data.task) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'task is required when type is "agent"',
+      path: ["task"]
+    });
+  }
+  if (data.type === "process" && !data.command) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'command is required when type is "process"',
+      path: ["command"]
+    });
+  }
+});
+function createStartTaskTool(starters) {
+  return {
+    id: "start_task",
+    description: "Start a background task without waiting for completion. Returns immediately with a task ID. Use wait_for or check_task to monitor progress.",
+    inputSchema: StartTaskInputSchema,
+    execute: async (rawInput, context) => {
+      const input = StartTaskInputSchema.parse(rawInput);
+      const starter = starters.get(input.type);
+      if (!starter) {
+        return {
+          success: false,
+          error: `No task starter registered for type '${input.type}'. Available types: ${Array.from(starters.keys()).join(", ") || "none"}`
+        };
+      }
+      try {
+        const { taskId, promise } = await starter.start(input);
+        const registerOptions = {
+          notify: input.notify,
+          ...input.timeout !== void 0 && { timeout: input.timeout }
+        };
+        if (input.type === "agent") {
+          context.taskRegistry.register(
+            {
+              type: "agent",
+              taskId,
+              agentId: taskId,
+              // Using taskId as agentId for now
+              taskDescription: input.task ?? "",
+              promise
+            },
+            registerOptions
+          );
+        } else if (input.type === "process") {
+          context.taskRegistry.register(
+            {
+              type: "process",
+              taskId,
+              processId: taskId,
+              command: input.command ?? "",
+              promise
+            },
+            registerOptions
+          );
+        } else {
+          context.taskRegistry.register(
+            {
+              type: "generic",
+              taskId,
+              description: input.description ?? "Generic task",
+              promise
+            },
+            registerOptions
+          );
+        }
+        return {
+          success: true,
+          taskId,
+          status: "running"
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+      }
+    }
+  };
+}
+function createGenericTaskStarter() {
+  let taskCounter = 0;
+  return {
+    async start(input) {
+      const taskId = `generic-${++taskCounter}`;
+      const promise = new Promise((resolve) => {
+        setTimeout(() => {
+          resolve({ completed: true, description: input.description });
+        }, 1e3);
+      });
+      return { taskId, promise };
+    }
+  };
+}
+export {
+  StartTaskInputSchema,
+  createGenericTaskStarter,
+  createStartTaskTool
+};

package/dist/tools/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/tools/types.d.cts

@@ -0,0 +1,30 @@
+import { TaskRegistry } from '../task-registry.cjs';
+import { ConditionEngine } from '../condition-engine.cjs';
+import { SignalBus } from '../signal-bus.cjs';
+import '../types.cjs';
+
+/**
+ * Tool Types
+ *
+ * Shared types for orchestration tools.
+ */
+
+/**
+ * Context provided to orchestration tools
+ */
+interface OrchestrationToolContext {
+    taskRegistry: TaskRegistry;
+    conditionEngine: ConditionEngine;
+    signalBus: SignalBus;
+}
+/**
+ * Base tool interface matching @dexto/core InternalTool
+ */
+interface OrchestrationTool {
+    id: string;
+    description: string;
+    inputSchema: unknown;
+    execute: (input: unknown, context: OrchestrationToolContext) => Promise<unknown>;
+}
+
+export type { OrchestrationTool, OrchestrationToolContext };

package/dist/tools/types.d.ts

@@ -0,0 +1,30 @@
+import { TaskRegistry } from '../task-registry.js';
+import { ConditionEngine } from '../condition-engine.js';
+import { SignalBus } from '../signal-bus.js';
+import '../types.js';
+
+/**
+ * Tool Types
+ *
+ * Shared types for orchestration tools.
+ */
+
+/**
+ * Context provided to orchestration tools
+ */
+interface OrchestrationToolContext {
+    taskRegistry: TaskRegistry;
+    conditionEngine: ConditionEngine;
+    signalBus: SignalBus;
+}
+/**
+ * Base tool interface matching @dexto/core InternalTool
+ */
+interface OrchestrationTool {
+    id: string;
+    description: string;
+    inputSchema: unknown;
+    execute: (input: unknown, context: OrchestrationToolContext) => Promise<unknown>;
+}
+
+export type { OrchestrationTool, OrchestrationToolContext };

package/dist/tools/wait-for.cjs

@@ -0,0 +1,116 @@
+"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 wait_for_exports = {};
+__export(wait_for_exports, {
+  WaitForInputSchema: () => WaitForInputSchema,
+  createWaitForTool: () => createWaitForTool
+});
+module.exports = __toCommonJS(wait_for_exports);
+var import_zod = require("zod");
+var import_crypto = require("crypto");
+var import_condition_engine = require("../condition-engine.js");
+const WaitForInputSchema = import_zod.z.object({
+  /** Wait for a single task */
+  taskId: import_zod.z.string().optional().describe("Task ID to wait for"),
+  /** Wait for multiple tasks */
+  taskIds: import_zod.z.array(import_zod.z.string()).optional().describe("Array of task IDs to wait for"),
+  /** Mode for multiple tasks: any = first to complete, all = wait for all */
+  mode: import_zod.z.enum(["any", "all"]).optional().default("all").describe('Wait mode: "any" returns when first completes, "all" waits for all'),
+  /** Timeout in milliseconds */
+  timeout: import_zod.z.number().positive().optional().describe("Maximum time to wait in milliseconds")
+}).strict().refine(
+  (data) => data.taskId !== void 0 || data.taskIds !== void 0 && data.taskIds.length > 0,
+  { message: "Either taskId or taskIds must be provided" }
+);
+function buildCondition(input) {
+  const taskIds = input.taskId ? [input.taskId] : input.taskIds ?? [];
+  if (taskIds.length === 0) {
+    throw new Error("At least one taskId is required");
+  }
+  const firstTaskId = taskIds[0];
+  let baseCondition;
+  if (taskIds.length === 1) {
+    baseCondition = { type: "task", taskId: firstTaskId };
+  } else if (input.mode === "any") {
+    baseCondition = import_condition_engine.ConditionEngine.createAnyTask(taskIds);
+  } else {
+    baseCondition = import_condition_engine.ConditionEngine.createAllTasks(taskIds);
+  }
+  if (input.timeout !== void 0) {
+    return {
+      type: "race",
+      task: baseCondition,
+      timeout: {
+        type: "timeout",
+        ms: input.timeout,
+        conditionId: `timeout-${(0, import_crypto.randomUUID)().slice(0, 8)}`
+      }
+    };
+  }
+  return baseCondition;
+}
+function formatOutput(signal, allSignals) {
+  if (signal.type === "timeout") {
+    return {
+      taskId: signal.conditionId,
+      status: "timeout",
+      error: "Wait timed out"
+    };
+  }
+  const baseOutput = {
+    taskId: "taskId" in signal ? signal.taskId : "",
+    status: signal.type === "task:completed" ? "completed" : signal.type === "task:failed" ? "failed" : "cancelled"
+  };
+  if (signal.type === "task:completed") {
+    baseOutput.result = signal.result;
+  } else if (signal.type === "task:failed") {
+    baseOutput.error = signal.error;
+  }
+  if (allSignals && allSignals.length > 1) {
+    baseOutput.allResults = allSignals.map((s) => {
+      if (s.type === "task:completed") {
+        return { taskId: s.taskId, status: "completed", result: s.result };
+      } else if (s.type === "task:failed") {
+        return { taskId: s.taskId, status: "failed", error: s.error };
+      } else if (s.type === "task:cancelled") {
+        return { taskId: s.taskId, status: "cancelled" };
+      }
+      return { taskId: "", status: "failed", error: "Unknown signal type" };
+    });
+  }
+  return baseOutput;
+}
+function createWaitForTool() {
+  return {
+    id: "wait_for",
+    description: "Wait for background task(s) to complete. Blocks execution until the condition is met. Use taskId for a single task, or taskIds with mode for multiple tasks.",
+    inputSchema: WaitForInputSchema,
+    execute: async (rawInput, context) => {
+      const input = WaitForInputSchema.parse(rawInput);
+      const condition = buildCondition(input);
+      const { signal, allSignals } = await context.conditionEngine.wait(condition);
+      return formatOutput(signal, allSignals);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WaitForInputSchema,
+  createWaitForTool
+});

package/dist/tools/wait-for.d.cts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { OrchestrationTool } from './types.cjs';
+import '../task-registry.cjs';
+import '../types.cjs';
+import '../signal-bus.cjs';
+import '../condition-engine.cjs';
+
+/**
+ * wait_for Tool
+ *
+ * Suspends agent execution until condition is met using a blocking promise.
+ * TurnExecutor naturally awaits tool execution, so this works seamlessly.
+ */
+
+/**
+ * Input schema for wait_for tool
+ */
+declare const WaitForInputSchema: z.ZodEffects<z.ZodObject<{
+    /** Wait for a single task */
+    taskId: z.ZodOptional<z.ZodString>;
+    /** Wait for multiple tasks */
+    taskIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Mode for multiple tasks: any = first to complete, all = wait for all */
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["any", "all"]>>>;
+    /** Timeout in milliseconds */
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    mode: "any" | "all";
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+}, {
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+    mode?: "any" | "all" | undefined;
+}>, {
+    mode: "any" | "all";
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+}, {
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+    mode?: "any" | "all" | undefined;
+}>;
+type WaitForInput = z.infer<typeof WaitForInputSchema>;
+/**
+ * Output from wait_for tool
+ */
+interface WaitForOutput {
+    /** Task ID that triggered the return (for 'any' mode) */
+    taskId: string;
+    /** Final status */
+    status: 'completed' | 'failed' | 'cancelled' | 'timeout';
+    /** Result if completed */
+    result?: unknown;
+    /** Error if failed */
+    error?: string;
+    /** All results for 'all' mode */
+    allResults?: Array<{
+        taskId: string;
+        status: 'completed' | 'failed' | 'cancelled';
+        result?: unknown;
+        error?: string;
+    }>;
+}
+/**
+ * Create the wait_for tool
+ */
+declare function createWaitForTool(): OrchestrationTool;
+
+export { type WaitForInput, WaitForInputSchema, type WaitForOutput, createWaitForTool };

package/dist/tools/wait-for.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { OrchestrationTool } from './types.js';
+import '../task-registry.js';
+import '../types.js';
+import '../signal-bus.js';
+import '../condition-engine.js';
+
+/**
+ * wait_for Tool
+ *
+ * Suspends agent execution until condition is met using a blocking promise.
+ * TurnExecutor naturally awaits tool execution, so this works seamlessly.
+ */
+
+/**
+ * Input schema for wait_for tool
+ */
+declare const WaitForInputSchema: z.ZodEffects<z.ZodObject<{
+    /** Wait for a single task */
+    taskId: z.ZodOptional<z.ZodString>;
+    /** Wait for multiple tasks */
+    taskIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Mode for multiple tasks: any = first to complete, all = wait for all */
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["any", "all"]>>>;
+    /** Timeout in milliseconds */
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    mode: "any" | "all";
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+}, {
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+    mode?: "any" | "all" | undefined;
+}>, {
+    mode: "any" | "all";
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+}, {
+    timeout?: number | undefined;
+    taskId?: string | undefined;
+    taskIds?: string[] | undefined;
+    mode?: "any" | "all" | undefined;
+}>;
+type WaitForInput = z.infer<typeof WaitForInputSchema>;
+/**
+ * Output from wait_for tool
+ */
+interface WaitForOutput {
+    /** Task ID that triggered the return (for 'any' mode) */
+    taskId: string;
+    /** Final status */
+    status: 'completed' | 'failed' | 'cancelled' | 'timeout';
+    /** Result if completed */
+    result?: unknown;
+    /** Error if failed */
+    error?: string;
+    /** All results for 'all' mode */
+    allResults?: Array<{
+        taskId: string;
+        status: 'completed' | 'failed' | 'cancelled';
+        result?: unknown;
+        error?: string;
+    }>;
+}
+/**
+ * Create the wait_for tool
+ */
+declare function createWaitForTool(): OrchestrationTool;
+
+export { type WaitForInput, WaitForInputSchema, type WaitForOutput, createWaitForTool };

package/dist/tools/wait-for.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { randomUUID } from "crypto";
+import { ConditionEngine } from "../condition-engine.js";
+const WaitForInputSchema = z.object({
+  /** Wait for a single task */
+  taskId: z.string().optional().describe("Task ID to wait for"),
+  /** Wait for multiple tasks */
+  taskIds: z.array(z.string()).optional().describe("Array of task IDs to wait for"),
+  /** Mode for multiple tasks: any = first to complete, all = wait for all */
+  mode: z.enum(["any", "all"]).optional().default("all").describe('Wait mode: "any" returns when first completes, "all" waits for all'),
+  /** Timeout in milliseconds */
+  timeout: z.number().positive().optional().describe("Maximum time to wait in milliseconds")
+}).strict().refine(
+  (data) => data.taskId !== void 0 || data.taskIds !== void 0 && data.taskIds.length > 0,
+  { message: "Either taskId or taskIds must be provided" }
+);
+function buildCondition(input) {
+  const taskIds = input.taskId ? [input.taskId] : input.taskIds ?? [];
+  if (taskIds.length === 0) {
+    throw new Error("At least one taskId is required");
+  }
+  const firstTaskId = taskIds[0];
+  let baseCondition;
+  if (taskIds.length === 1) {
+    baseCondition = { type: "task", taskId: firstTaskId };
+  } else if (input.mode === "any") {
+    baseCondition = ConditionEngine.createAnyTask(taskIds);
+  } else {
+    baseCondition = ConditionEngine.createAllTasks(taskIds);
+  }
+  if (input.timeout !== void 0) {
+    return {
+      type: "race",
+      task: baseCondition,
+      timeout: {
+        type: "timeout",
+        ms: input.timeout,
+        conditionId: `timeout-${randomUUID().slice(0, 8)}`
+      }
+    };
+  }
+  return baseCondition;
+}
+function formatOutput(signal, allSignals) {
+  if (signal.type === "timeout") {
+    return {
+      taskId: signal.conditionId,
+      status: "timeout",
+      error: "Wait timed out"
+    };
+  }
+  const baseOutput = {
+    taskId: "taskId" in signal ? signal.taskId : "",
+    status: signal.type === "task:completed" ? "completed" : signal.type === "task:failed" ? "failed" : "cancelled"
+  };
+  if (signal.type === "task:completed") {
+    baseOutput.result = signal.result;
+  } else if (signal.type === "task:failed") {
+    baseOutput.error = signal.error;
+  }
+  if (allSignals && allSignals.length > 1) {
+    baseOutput.allResults = allSignals.map((s) => {
+      if (s.type === "task:completed") {
+        return { taskId: s.taskId, status: "completed", result: s.result };
+      } else if (s.type === "task:failed") {
+        return { taskId: s.taskId, status: "failed", error: s.error };
+      } else if (s.type === "task:cancelled") {
+        return { taskId: s.taskId, status: "cancelled" };
+      }
+      return { taskId: "", status: "failed", error: "Unknown signal type" };
+    });
+  }
+  return baseOutput;
+}
+function createWaitForTool() {
+  return {
+    id: "wait_for",
+    description: "Wait for background task(s) to complete. Blocks execution until the condition is met. Use taskId for a single task, or taskIds with mode for multiple tasks.",
+    inputSchema: WaitForInputSchema,
+    execute: async (rawInput, context) => {
+      const input = WaitForInputSchema.parse(rawInput);
+      const condition = buildCondition(input);
+      const { signal, allSignals } = await context.conditionEngine.wait(condition);
+      return formatOutput(signal, allSignals);
+    }
+  };
+}
+export {
+  WaitForInputSchema,
+  createWaitForTool
+};

package/dist/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);