@holoscript/engine 6.0.3 → 6.0.4

package/dist/choreography/index.js

@@ -0,0 +1,1156 @@
+import "../chunk-AKLW2MUS.js";
+
+// src/choreography/ChoreographyTypes.ts
+var DEFAULT_RETRY_CONFIG = {
+  strategy: "exponential",
+  maxRetries: 3,
+  delay: 1e3,
+  backoffMultiplier: 2,
+  maxDelay: 3e4
+};
+var Constraints = {
+  timeout(ms, hard = true) {
+    return { type: "timeout", value: ms, hard, description: `Max ${ms}ms execution time` };
+  },
+  concurrency(max) {
+    return { type: "concurrency", value: max, description: `Max ${max} concurrent steps` };
+  },
+  trust(minLevel) {
+    return { type: "trust", value: minLevel, hard: true, description: `Min trust: ${minLevel}` };
+  }
+};
+
+// src/choreography/StepExecutor.ts
+import { EventEmitter } from "events";
+var DEFAULT_EXECUTOR_CONFIG = {
+  defaultTimeout: 3e4,
+  defaultRetry: DEFAULT_RETRY_CONFIG,
+  verbose: false
+};
+var StepExecutor = class extends EventEmitter {
+  config;
+  actionHandler = null;
+  runningSteps = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    super();
+    this.config = { ...DEFAULT_EXECUTOR_CONFIG, ...config };
+  }
+  /**
+   * Register the action handler for executing agent actions
+   */
+  setActionHandler(handler) {
+    this.actionHandler = handler;
+  }
+  /**
+   * Execute a single step
+   */
+  async execute(step, context) {
+    const startTime = Date.now();
+    if (this.shouldSkip(step, context)) {
+      const reason = "Condition not met";
+      this.emit("step:skipped", step, reason);
+      return {
+        stepId: step.id,
+        success: true,
+        outputs: {},
+        duration: 0,
+        error: void 0
+      };
+    }
+    const agent = context.agents.get(step.agentId);
+    if (!agent) {
+      throw new Error(`Agent not found: ${step.agentId}`);
+    }
+    const resolvedInputs = this.resolveInputs(step.inputs, context);
+    this.emit("step:inputs:resolved", step, resolvedInputs);
+    const retryConfig = {
+      ...this.config.defaultRetry,
+      ...step.retry || {}
+    };
+    let lastError = null;
+    let attempt = 0;
+    while (attempt <= retryConfig.maxRetries) {
+      try {
+        step.status = "running";
+        step.startedAt = Date.now();
+        step.retryAttempt = attempt;
+        this.emit("step:executing", step, agent);
+        const abortController = new AbortController();
+        this.runningSteps.set(step.id, abortController);
+        const timeout = step.timeout || this.config.defaultTimeout;
+        const outputs = await this.executeWithTimeout(
+          step,
+          agent,
+          resolvedInputs,
+          context,
+          timeout,
+          abortController.signal
+        );
+        this.runningSteps.delete(step.id);
+        step.status = "completed";
+        step.completedAt = Date.now();
+        step.duration = step.completedAt - step.startedAt;
+        const result = {
+          stepId: step.id,
+          success: true,
+          outputs,
+          duration: step.duration,
+          retries: attempt
+        };
+        this.emit("step:completed", step, result);
+        return result;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        this.runningSteps.delete(step.id);
+        if (lastError.message.includes("cancelled")) {
+          step.status = "failed";
+          step.completedAt = Date.now();
+          step.duration = step.completedAt - (step.startedAt || startTime);
+          step.error = lastError.message;
+          return {
+            stepId: step.id,
+            success: false,
+            outputs: {},
+            duration: step.duration,
+            error: step.error,
+            retries: attempt
+          };
+        }
+        if (attempt < retryConfig.maxRetries) {
+          if (retryConfig.condition && !retryConfig.condition(lastError, attempt)) {
+            break;
+          }
+          const delay = this.calculateDelay(retryConfig, attempt);
+          this.emit("step:retrying", step, attempt + 1, delay);
+          await this.sleep(delay);
+        }
+        attempt++;
+      }
+    }
+    step.status = "failed";
+    step.completedAt = Date.now();
+    step.duration = step.completedAt - (step.startedAt || startTime);
+    step.error = lastError?.message || "Unknown error";
+    this.emit("step:failed", step, lastError || new Error("Unknown error"));
+    return {
+      stepId: step.id,
+      success: false,
+      outputs: {},
+      duration: step.duration,
+      error: step.error,
+      retries: attempt - 1
+    };
+  }
+  /**
+   * Cancel a running step
+   */
+  cancel(stepId) {
+    const controller = this.runningSteps.get(stepId);
+    if (controller) {
+      controller.abort();
+      this.runningSteps.delete(stepId);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Check if any steps are running
+   */
+  isRunning(stepId) {
+    if (stepId) {
+      return this.runningSteps.has(stepId);
+    }
+    return this.runningSteps.size > 0;
+  }
+  // ==========================================================================
+  // PRIVATE METHODS
+  // ==========================================================================
+  /**
+   * Check if step should be skipped
+   */
+  shouldSkip(step, context) {
+    if (!step.condition) return false;
+    if (typeof step.condition === "function") {
+      return !step.condition(context);
+    }
+    try {
+      return !this.evaluateCondition(step.condition, context);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Evaluate a string condition
+   */
+  evaluateCondition(condition, context) {
+    const stepRefRegex = /step#(\w+)\.outputs\.(\w+)/g;
+    let evaluated = condition;
+    evaluated = evaluated.replace(stepRefRegex, (_, stepId, outputKey) => {
+      const outputs = context.stepOutputs.get(stepId);
+      if (outputs && outputKey in outputs) {
+        const value2 = outputs[outputKey];
+        if (typeof value2 === "string") {
+          return `"${value2}"`;
+        }
+        return String(value2);
+      }
+      return "undefined";
+    });
+    const eqMatch = evaluated.match(/^(.+)\s*==\s*(.+)$/);
+    if (eqMatch) {
+      const [, left, right] = eqMatch;
+      return this.parseValue(left.trim()) === this.parseValue(right.trim());
+    }
+    const value = this.parseValue(evaluated.trim());
+    return Boolean(value);
+  }
+  /**
+   * Parse a string value
+   */
+  parseValue(str) {
+    if (str === "true") return true;
+    if (str === "false") return false;
+    if (str === "null") return null;
+    if (str === "undefined") return void 0;
+    if (/^-?\d+$/.test(str)) return parseInt(str, 10);
+    if (/^-?\d+\.\d+$/.test(str)) return parseFloat(str);
+    if (str.startsWith('"') && str.endsWith('"')) {
+      return str.slice(1, -1);
+    }
+    return str;
+  }
+  /**
+   * Resolve input references
+   */
+  resolveInputs(inputs, context) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(inputs)) {
+      if (typeof value === "string") {
+        const templateRef = value.match(/^\$\{([\w-]+)\.([\w-]+)\}$/);
+        if (templateRef) {
+          const [, stepName, outputKey] = templateRef;
+          let outputs = context.stepOutputs.get(stepName);
+          if (!outputs && context.plan?.steps) {
+            const referencedStep = context.plan.steps.find(
+              (s) => s.name === stepName || s.id === stepName
+            );
+            if (referencedStep) {
+              outputs = context.stepOutputs.get(referencedStep.id);
+            }
+          }
+          if (outputs) {
+            resolved[key] = outputs[outputKey];
+            continue;
+          }
+        }
+        const stepRef = value.match(/^step#(\w+)\.outputs\.(\w+)$/);
+        if (stepRef) {
+          const [, stepId, outputKey] = stepRef;
+          const outputs = context.stepOutputs.get(stepId);
+          resolved[key] = outputs?.[outputKey];
+          continue;
+        }
+        const stateRef = value.match(/^state\.(\w+)$/);
+        if (stateRef) {
+          resolved[key] = context.variables[stateRef[1]];
+          continue;
+        }
+      }
+      resolved[key] = value;
+    }
+    return resolved;
+  }
+  /**
+   * Execute with timeout
+   */
+  async executeWithTimeout(step, agent, inputs, context, timeout, signal) {
+    if (!this.actionHandler) {
+      throw new Error("No action handler registered");
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.emit("step:timeout", step, timeout);
+        reject(new Error(`Step timed out after ${timeout}ms`));
+      }, timeout);
+      signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new Error("Step was cancelled"));
+      });
+      this.actionHandler(agent, step.action, inputs, context).then((outputs) => {
+        clearTimeout(timer);
+        resolve(outputs);
+      }).catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+  }
+  /**
+   * Calculate retry delay
+   */
+  calculateDelay(config, attempt) {
+    let delay = config.delay;
+    switch (config.strategy) {
+      case "none":
+        return 0;
+      case "immediate":
+        return 0;
+      case "fixed":
+        return delay;
+      case "exponential":
+        delay = delay * Math.pow(config.backoffMultiplier || 2, attempt);
+        break;
+    }
+    if (config.maxDelay && delay > config.maxDelay) {
+      delay = config.maxDelay;
+    }
+    const jitter = delay * 0.1 * (Math.random() * 2 - 1);
+    return Math.round(delay + jitter);
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+var defaultExecutor = null;
+function getDefaultExecutor() {
+  if (!defaultExecutor) {
+    defaultExecutor = new StepExecutor();
+  }
+  return defaultExecutor;
+}
+function resetDefaultExecutor() {
+  defaultExecutor = null;
+}
+
+// src/choreography/ChoreographyPlanner.ts
+import { CapabilityMatcher } from "@holoscript/framework/agents";
+function generateId() {
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var ChoreographyPlanner = class {
+  matcher = new CapabilityMatcher();
+  /**
+   * Create a choreography plan from definition
+   */
+  createPlan(definition) {
+    const planId = generateId();
+    const _agents = new Map(definition.agents.map((a) => [a.id, a]));
+    const steps = definition.steps.map((stepDef) => {
+      const agentId = this.resolveAgent(stepDef.agent, definition.agents);
+      if (!agentId) {
+        throw new Error(
+          `No agent found for step ${stepDef.id || stepDef.name}: ${JSON.stringify(stepDef.agent)}`
+        );
+      }
+      const outputs = {};
+      if (stepDef.outputs) {
+        for (const [key, value] of Object.entries(stepDef.outputs)) {
+          if (typeof value === "string") {
+            outputs[key] = { key, type: "unknown" };
+          } else {
+            outputs[key] = value;
+          }
+        }
+      }
+      const step = {
+        id: stepDef.id || `step_${generateId()}`,
+        name: stepDef.name,
+        description: stepDef.description,
+        agentId,
+        action: stepDef.action,
+        inputs: stepDef.inputs || {},
+        outputs,
+        dependencies: stepDef.dependencies || stepDef.dependsOn || [],
+        parallelGroup: stepDef.parallelGroup,
+        status: "pending",
+        timeout: stepDef.timeout,
+        retry: stepDef.retries !== void 0 ? { maxRetries: stepDef.retries } : void 0,
+        condition: stepDef.condition,
+        hitlGate: stepDef.hitlGate,
+        fallbackStepId: stepDef.fallbackStepId
+      };
+      return step;
+    });
+    const stepNameToId = /* @__PURE__ */ new Map();
+    for (const step of steps) {
+      if (step.name) {
+        stepNameToId.set(step.name, step.id);
+      }
+      stepNameToId.set(step.id, step.id);
+    }
+    for (const step of steps) {
+      step.dependencies = step.dependencies.map((dep) => {
+        const resolvedId = stepNameToId.get(dep);
+        if (!resolvedId) {
+          throw new Error(`Unknown step dependency "${dep}" in step "${step.name || step.id}"`);
+        }
+        return resolvedId;
+      });
+    }
+    let fallback;
+    if (definition.fallback) {
+      fallback = this.createPlan(definition.fallback);
+    }
+    const plan2 = {
+      id: planId,
+      name: definition.name,
+      goal: definition.goal,
+      steps,
+      participants: definition.agents,
+      constraints: definition.constraints || [],
+      fallback,
+      status: "draft",
+      createdAt: Date.now(),
+      priority: definition.priority,
+      tags: definition.tags,
+      metadata: definition.metadata
+    };
+    return plan2;
+  }
+  /**
+   * Validate a choreography plan
+   */
+  validate(plan2) {
+    const errors = [];
+    const warnings = [];
+    const stepIds = new Set(plan2.steps.map((s) => s.id));
+    const agentIds = new Set(plan2.participants.map((a) => a.id));
+    if (plan2.steps.length === 0) {
+      errors.push("Plan has no steps");
+    }
+    for (const step of plan2.steps) {
+      if (!agentIds.has(step.agentId)) {
+        errors.push(`Step '${step.id}': Agent '${step.agentId}' not in participants`);
+      }
+      if (!step.action) {
+        errors.push(`Step '${step.id}': No action specified`);
+      }
+      for (const depId of step.dependencies) {
+        if (!stepIds.has(depId)) {
+          errors.push(`Step '${step.id}': Dependency '${depId}' does not exist`);
+        }
+        if (depId === step.id) {
+          errors.push(`Step '${step.id}': Cannot depend on itself`);
+        }
+      }
+    }
+    const cycleCheck = this.detectCycles(plan2.steps);
+    if (cycleCheck) {
+      errors.push(`Circular dependency detected: ${cycleCheck.join(" -> ")}`);
+    }
+    if (!plan2.constraints.some((c) => c.type === "timeout")) {
+      warnings.push("No timeout constraint specified");
+    }
+    if (plan2.steps.some((s) => s.hitlGate) && !plan2.participants.some((a) => a.capabilities?.some((c) => c.type === "approve"))) {
+      warnings.push("HITL gate present but no approval agent in participants");
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+  /**
+   * Calculate execution order
+   */
+  calculateExecutionOrder(plan2) {
+    const graph = /* @__PURE__ */ new Map();
+    const inDegree = /* @__PURE__ */ new Map();
+    for (const step of plan2.steps) {
+      graph.set(step.id, step.dependencies);
+      inDegree.set(step.id, step.dependencies.length);
+    }
+    const flatOrder = [];
+    const parallelGroups = [];
+    const queue = [];
+    for (const [stepId, degree] of inDegree.entries()) {
+      if (degree === 0) {
+        queue.push(stepId);
+      }
+    }
+    while (queue.length > 0) {
+      const currentGroup = [...queue];
+      parallelGroups.push(currentGroup);
+      queue.length = 0;
+      for (const stepId of currentGroup) {
+        flatOrder.push(stepId);
+        for (const [otherId, deps] of graph.entries()) {
+          if (deps.includes(stepId)) {
+            const newDegree = (inDegree.get(otherId) || 0) - 1;
+            inDegree.set(otherId, newDegree);
+            if (newDegree === 0) {
+              queue.push(otherId);
+            }
+          }
+        }
+      }
+    }
+    return {
+      parallelGroups,
+      flatOrder,
+      graph
+    };
+  }
+  /**
+   * Clone and reset a plan for re-execution
+   */
+  resetPlan(plan2) {
+    return {
+      ...plan2,
+      id: generateId(),
+      status: "draft",
+      createdAt: Date.now(),
+      startedAt: void 0,
+      completedAt: void 0,
+      duration: void 0,
+      steps: plan2.steps.map((step) => ({
+        ...step,
+        status: "pending",
+        startedAt: void 0,
+        completedAt: void 0,
+        duration: void 0,
+        error: void 0,
+        retryAttempt: void 0
+      }))
+    };
+  }
+  // ==========================================================================
+  // PRIVATE METHODS
+  // ==========================================================================
+  /**
+   * Resolve agent from ID or capability query
+   */
+  resolveAgent(agentRef, agents) {
+    if (typeof agentRef === "string") {
+      const agent = agents.find((a) => a.id === agentRef || a.name === agentRef);
+      return agent?.id || null;
+    }
+    const matches = this.matcher.findMatches(agents, agentRef);
+    if (matches.length > 0) {
+      return matches[0].manifest.id;
+    }
+    return null;
+  }
+  /**
+   * Detect circular dependencies
+   */
+  detectCycles(steps) {
+    const visited = /* @__PURE__ */ new Set();
+    const recursionStack = /* @__PURE__ */ new Set();
+    const stepMap = new Map(steps.map((s) => [s.id, s]));
+    const dfs = (stepId, path) => {
+      if (recursionStack.has(stepId)) {
+        return [...path, stepId];
+      }
+      if (visited.has(stepId)) {
+        return null;
+      }
+      visited.add(stepId);
+      recursionStack.add(stepId);
+      const step = stepMap.get(stepId);
+      if (step) {
+        for (const depId of step.dependencies) {
+          const cycle = dfs(depId, [...path, stepId]);
+          if (cycle) return cycle;
+        }
+      }
+      recursionStack.delete(stepId);
+      return null;
+    };
+    for (const step of steps) {
+      const cycle = dfs(step.id, []);
+      if (cycle) return cycle;
+    }
+    return null;
+  }
+};
+var PlanBuilder = class {
+  definition;
+  planner = new ChoreographyPlanner();
+  constructor(goal) {
+    this.definition = {
+      goal,
+      agents: [],
+      steps: [],
+      constraints: []
+    };
+  }
+  /**
+   * Set plan name
+   */
+  name(name) {
+    this.definition.name = name;
+    return this;
+  }
+  /**
+   * Add an agent to the plan
+   */
+  agent(manifest) {
+    this.definition.agents.push(manifest);
+    return this;
+  }
+  /**
+   * Add multiple agents
+   */
+  agents(manifests) {
+    this.definition.agents.push(...manifests);
+    return this;
+  }
+  /**
+   * Add a step to the plan
+   */
+  step(definition) {
+    this.definition.steps.push(definition);
+    return this;
+  }
+  /**
+   * Add a constraint
+   */
+  constraint(constraint) {
+    this.definition.constraints.push(constraint);
+    return this;
+  }
+  /**
+   * Set timeout constraint
+   */
+  timeout(ms) {
+    this.definition.constraints.push({
+      type: "timeout",
+      value: ms,
+      hard: true,
+      description: `Maximum ${ms}ms execution time`
+    });
+    return this;
+  }
+  /**
+   * Set concurrency constraint
+   */
+  concurrency(max) {
+    this.definition.constraints.push({
+      type: "concurrency",
+      value: max,
+      description: `Maximum ${max} concurrent steps`
+    });
+    return this;
+  }
+  /**
+   * Set fallback plan
+   */
+  fallback(fallbackPlan) {
+    this.definition.fallback = fallbackPlan;
+    return this;
+  }
+  /**
+   * Set priority
+   */
+  priority(priority) {
+    this.definition.priority = priority;
+    return this;
+  }
+  /**
+   * Add tags
+   */
+  tags(...tags) {
+    this.definition.tags = [...this.definition.tags || [], ...tags];
+    return this;
+  }
+  /**
+   * Set metadata
+   */
+  metadata(meta) {
+    this.definition.metadata = { ...this.definition.metadata || {}, ...meta };
+    return this;
+  }
+  /**
+   * Build and validate the plan
+   */
+  build() {
+    const plan2 = this.planner.createPlan(this.definition);
+    const validation = this.planner.validate(plan2);
+    if (!validation.valid) {
+      throw new Error(`Plan validation failed:
+${validation.errors.join("\n")}`);
+    }
+    return plan2;
+  }
+  /**
+   * Build without validation (for testing)
+   */
+  buildUnsafe() {
+    return this.planner.createPlan(this.definition);
+  }
+};
+function plan(goal) {
+  return new PlanBuilder(goal);
+}
+var defaultPlanner = null;
+function getDefaultPlanner() {
+  if (!defaultPlanner) {
+    defaultPlanner = new ChoreographyPlanner();
+  }
+  return defaultPlanner;
+}
+
+// src/choreography/ChoreographyEngine.ts
+import { EventEmitter as EventEmitter2 } from "events";
+var DEFAULT_ENGINE_CONFIG = {
+  maxConcurrency: 4,
+  defaultTimeout: 3e4,
+  executeFallback: true,
+  autoHitlPause: true,
+  verbose: false
+};
+var ChoreographyEngine = class extends EventEmitter2 {
+  config;
+  planner;
+  executor;
+  registry = null;
+  activePlans = /* @__PURE__ */ new Map();
+  actionHandler = null;
+  constructor(config = {}) {
+    super();
+    this.config = { ...DEFAULT_ENGINE_CONFIG, ...config };
+    this.planner = getDefaultPlanner();
+    this.executor = getDefaultExecutor();
+    this.executor.on("step:completed", (step, result) => {
+      const state = this.findPlanWithStep(step.id);
+      if (state) {
+        this.emit("step:completed", result, state.plan);
+      }
+    });
+    this.executor.on("step:failed", (step, error) => {
+      const state = this.findPlanWithStep(step.id);
+      if (state) {
+        this.emit("step:failed", step, error, state.plan);
+      }
+    });
+    this.executor.on("step:retrying", (step, attempt, _delay) => {
+      const state = this.findPlanWithStep(step.id);
+      if (state) {
+        this.emit("step:retrying", step, attempt, state.plan);
+      }
+    });
+  }
+  /**
+   * Set the agent registry
+   */
+  setRegistry(registry) {
+    this.registry = registry;
+  }
+  /**
+   * Set the action handler for executing agent actions
+   */
+  setActionHandler(handler) {
+    this.actionHandler = handler;
+    this.executor.setActionHandler(handler);
+  }
+  /**
+   * Create a new choreography plan
+   */
+  createPlan(goal, agents, steps) {
+    const plan2 = {
+      id: this.generateId(),
+      goal,
+      steps: [...steps],
+      participants: [...agents],
+      constraints: [],
+      status: "draft",
+      createdAt: Date.now()
+    };
+    this.emit("plan:created", plan2);
+    return plan2;
+  }
+  /**
+   * Execute a choreography plan
+   */
+  async execute(plan2, variables = {}) {
+    if (!this.actionHandler) {
+      throw new Error("No action handler registered. Call setActionHandler first.");
+    }
+    const validation = this.planner.validate(plan2);
+    if (!validation.valid) {
+      throw new Error(`Plan validation failed: ${validation.errors.join(", ")}`);
+    }
+    const executionOrder = this.planner.calculateExecutionOrder(plan2);
+    const state = {
+      plan: plan2,
+      stepResults: /* @__PURE__ */ new Map(),
+      stepOutputs: /* @__PURE__ */ new Map(),
+      executionOrder,
+      currentGroup: 0,
+      paused: false,
+      cancelled: false,
+      hitlPending: /* @__PURE__ */ new Set(),
+      startTime: Date.now(),
+      variables
+    };
+    this.activePlans.set(plan2.id, state);
+    plan2.status = "running";
+    plan2.startedAt = state.startTime;
+    this.emit("plan:started", plan2);
+    try {
+      const result = await this.executePlan(state);
+      if (!result.success && plan2.fallback && this.config.executeFallback) {
+        this.emit("plan:failed", plan2, new Error(result.error || "Unknown error"));
+        const fallbackResult = await this.execute(plan2.fallback, variables);
+        return {
+          ...fallbackResult,
+          usedFallback: true
+        };
+      }
+      plan2.status = result.success ? "completed" : "failed";
+      plan2.completedAt = Date.now();
+      plan2.duration = plan2.completedAt - (plan2.startedAt || state.startTime);
+      this.emit("plan:completed", result);
+      return result;
+    } catch (error) {
+      plan2.status = "failed";
+      plan2.completedAt = Date.now();
+      plan2.duration = plan2.completedAt - (plan2.startedAt || state.startTime);
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit("plan:failed", plan2, err);
+      return {
+        planId: plan2.id,
+        success: false,
+        status: "failed",
+        stepResults: Array.from(state.stepResults.values()),
+        duration: plan2.duration,
+        stepsCompleted: state.stepResults.size,
+        stepsFailed: Array.from(state.stepResults.values()).filter((r) => !r.success).length,
+        stepsSkipped: 0,
+        error: err.message,
+        finalOutputs: {}
+      };
+    } finally {
+      this.activePlans.delete(plan2.id);
+    }
+  }
+  /**
+   * Pause a running plan
+   */
+  async pause(planId) {
+    const state = this.activePlans.get(planId);
+    if (!state) {
+      return;
+    }
+    state.paused = true;
+    state.plan.status = "paused";
+    this.emit("plan:paused", state.plan);
+  }
+  /**
+   * Resume a paused plan
+   */
+  async resume(planId) {
+    const state = this.activePlans.get(planId);
+    if (!state) {
+      return;
+    }
+    if (!state.paused) {
+      return;
+    }
+    state.paused = false;
+    state.plan.status = "running";
+    this.emit("plan:resumed", state.plan);
+  }
+  /**
+   * Cancel a running plan
+   */
+  async cancel(planId) {
+    const state = this.activePlans.get(planId);
+    if (!state) {
+      return;
+    }
+    state.cancelled = true;
+    state.plan.status = "cancelled";
+    for (const step of state.plan.steps) {
+      if (step.status === "running") {
+        this.executor.cancel(step.id);
+        step.status = "cancelled";
+      }
+    }
+    this.emit("plan:cancelled", state.plan);
+  }
+  /**
+   * Approve a HITL gate
+   */
+  approveHitl(planId, stepId) {
+    const state = this.activePlans.get(planId);
+    if (!state) {
+      throw new Error(`Plan not found: ${planId}`);
+    }
+    if (!state.hitlPending.has(stepId)) {
+      throw new Error(`Step ${stepId} is not pending HITL approval`);
+    }
+    state.hitlPending.delete(stepId);
+    const step = state.plan.steps.find((s) => s.id === stepId);
+    if (step) {
+      this.emit("hitl:approved", step, state.plan);
+    }
+  }
+  /**
+   * Reject a HITL gate
+   */
+  rejectHitl(planId, stepId, reason) {
+    const state = this.activePlans.get(planId);
+    if (!state) {
+      throw new Error(`Plan not found: ${planId}`);
+    }
+    if (!state.hitlPending.has(stepId)) {
+      throw new Error(`Step ${stepId} is not pending HITL approval`);
+    }
+    state.hitlPending.delete(stepId);
+    const step = state.plan.steps.find((s) => s.id === stepId);
+    if (step) {
+      step.status = "failed";
+      step.error = `HITL rejected: ${reason}`;
+      this.emit("hitl:rejected", step, reason, state.plan);
+    }
+  }
+  /**
+   * Get active plan IDs
+   */
+  getActivePlans() {
+    return Array.from(this.activePlans.keys());
+  }
+  /**
+   * Get plan status
+   */
+  getPlanStatus(planId) {
+    const state = this.activePlans.get(planId);
+    return state?.plan.status || null;
+  }
+  // ==========================================================================
+  // PRIVATE METHODS
+  // ==========================================================================
+  /**
+   * Execute the plan
+   */
+  async executePlan(state) {
+    const { plan: _plan, executionOrder } = state;
+    for (const group of executionOrder.parallelGroups) {
+      while (state.paused && !state.cancelled) {
+        await this.sleep(100);
+      }
+      if (state.cancelled) {
+        break;
+      }
+      await this.executeGroup(state, group);
+      const failed = group.some((stepId) => {
+        const result = state.stepResults.get(stepId);
+        return result && !result.success;
+      });
+      if (failed) {
+        break;
+      }
+      state.currentGroup++;
+    }
+    return this.buildResult(state);
+  }
+  /**
+   * Execute a group of steps (potentially in parallel)
+   */
+  async executeGroup(state, stepIds) {
+    const steps = stepIds.map((id) => state.plan.steps.find((s) => s.id === id)).filter((s) => s !== void 0);
+    const concurrency = this.getConcurrencyLimit(state.plan);
+    const batches = this.chunk(steps, concurrency);
+    for (const batch of batches) {
+      if (state.cancelled) break;
+      const promises = batch.map((step) => this.executeStep(state, step));
+      await Promise.all(promises);
+    }
+  }
+  /**
+   * Execute a single step
+   */
+  async executeStep(state, step) {
+    if (step.hitlGate && this.config.autoHitlPause) {
+      state.hitlPending.add(step.id);
+      this.emit("hitl:required", step, state.plan);
+      while (state.hitlPending.has(step.id) && !state.cancelled) {
+        await this.sleep(100);
+      }
+      if (state.cancelled) {
+        step.status = "cancelled";
+        return;
+      }
+      if (step.status === "failed") {
+        state.stepResults.set(step.id, {
+          stepId: step.id,
+          success: false,
+          outputs: {},
+          duration: 0,
+          error: step.error
+        });
+        return;
+      }
+    }
+    const context = this.buildStepContext(state, step);
+    this.emit("step:started", step, state.plan);
+    const result = await this.executor.execute(step, context);
+    if (!result.success && step.fallbackStepId && this.config.executeFallback) {
+      const fallbackStep = state.plan.steps.find(
+        (s) => s.id === step.fallbackStepId || s.name === step.fallbackStepId
+      );
+      if (fallbackStep) {
+        let fallbackResult = state.stepResults.get(fallbackStep.id);
+        if (!fallbackResult && fallbackStep.status === "running") {
+          while (!state.stepResults.has(fallbackStep.id) && !state.cancelled) {
+            await this.sleep(50);
+          }
+          fallbackResult = state.stepResults.get(fallbackStep.id);
+        }
+        if (!fallbackResult && fallbackStep.status === "pending") {
+          await this.executeStep(state, fallbackStep);
+          fallbackResult = state.stepResults.get(fallbackStep.id);
+        }
+        if (fallbackResult?.success) {
+          state.stepResults.set(step.id, {
+            stepId: step.id,
+            success: true,
+            outputs: fallbackResult.outputs,
+            duration: result.duration,
+            usedFallback: true
+          });
+          state.stepOutputs.set(step.id, fallbackResult.outputs);
+          return;
+        }
+      }
+    }
+    state.stepResults.set(step.id, result);
+    if (result.success) {
+      state.stepOutputs.set(step.id, result.outputs);
+    }
+  }
+  /**
+   * Build step context
+   */
+  buildStepContext(state, step) {
+    const agents = new Map(state.plan.participants.map((a) => [a.id, a]));
+    return {
+      plan: state.plan,
+      currentStep: step,
+      agents,
+      stepOutputs: state.stepOutputs,
+      variables: state.variables,
+      startTime: state.startTime,
+      elapsedTime: Date.now() - state.startTime
+    };
+  }
+  /**
+   * Build final result
+   */
+  buildResult(state) {
+    const stepResults = Array.from(state.stepResults.values());
+    const completed = stepResults.filter((r) => r.success).length;
+    const failed = stepResults.filter((r) => !r.success).length;
+    const skipped = state.plan.steps.length - stepResults.length;
+    const completedSteps = state.plan.steps.filter((step) => {
+      const result = state.stepResults.get(step.id);
+      return result?.success;
+    });
+    const failedSteps = state.plan.steps.filter((step) => {
+      const result = state.stepResults.get(step.id);
+      return result && !result.success;
+    });
+    const terminalSteps = state.plan.steps.filter(
+      (s) => !state.plan.steps.some((other) => other.dependencies.includes(s.id))
+    );
+    const finalOutputs = {};
+    for (const step of terminalSteps) {
+      const outputs = state.stepOutputs.get(step.id);
+      if (outputs) {
+        Object.assign(finalOutputs, outputs);
+      }
+    }
+    const success = !state.cancelled && failed === 0 && skipped === 0;
+    return {
+      planId: state.plan.id,
+      success,
+      status: state.cancelled ? "cancelled" : success ? "completed" : "failed",
+      stepResults,
+      duration: Date.now() - state.startTime,
+      stepsCompleted: completed,
+      stepsFailed: failed,
+      stepsSkipped: skipped,
+      completedSteps,
+      failedSteps,
+      error: failed > 0 ? `${failed} step(s) failed` : void 0,
+      finalOutputs,
+      metrics: {
+        peakConcurrency: this.getConcurrencyLimit(state.plan)
+      }
+    };
+  }
+  /**
+   * Get concurrency limit from constraints
+   */
+  getConcurrencyLimit(plan2) {
+    const constraint = plan2.constraints.find((c) => c.type === "concurrency");
+    if (constraint && typeof constraint.value === "number") {
+      return constraint.value;
+    }
+    return this.config.maxConcurrency;
+  }
+  /**
+   * Find plan containing a step
+   */
+  findPlanWithStep(stepId) {
+    for (const state of this.activePlans.values()) {
+      if (state.plan.steps.some((s) => s.id === stepId)) {
+        return state;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Generate unique ID
+   */
+  generateId() {
+    return `plan_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+  /**
+   * Chunk array into batches
+   */
+  chunk(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+var defaultEngine = null;
+function getDefaultEngine() {
+  if (!defaultEngine) {
+    defaultEngine = new ChoreographyEngine();
+  }
+  return defaultEngine;
+}
+function resetDefaultEngine() {
+  defaultEngine = null;
+}
+export {
+  ChoreographyEngine,
+  ChoreographyPlanner,
+  Constraints,
+  DEFAULT_ENGINE_CONFIG,
+  DEFAULT_EXECUTOR_CONFIG,
+  DEFAULT_RETRY_CONFIG,
+  PlanBuilder,
+  StepExecutor,
+  getDefaultEngine,
+  getDefaultExecutor,
+  getDefaultPlanner,
+  plan,
+  resetDefaultEngine,
+  resetDefaultExecutor
+};