@simulacra-ai/orchestration 0.0.3 → 0.0.5

package/dist/index.cjs

@@ -0,0 +1,706 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BackgroundAgentPool: () => BackgroundAgentPool,
+  BackgroundOrchestrator: () => BackgroundOrchestrator,
+  BackgroundTaskPool: () => BackgroundTaskPool,
+  ORCHESTRATION_DEPTH_KEY: () => ORCHESTRATION_DEPTH_KEY,
+  OrchestrationToolkit: () => OrchestrationToolkit,
+  Orchestrator: () => Orchestrator,
+  ParallelAgentTask: () => ParallelAgentTask,
+  ParallelOrchestrator: () => ParallelOrchestrator,
+  SubagentOrchestrator: () => SubagentOrchestrator,
+  SubagentTask: () => SubagentTask
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/orchestrator.ts
+var import_core = require("@simulacra-ai/core");
+var ORCHESTRATION_TOOL_NAMES = /* @__PURE__ */ new Set(["subagent", "background", "parallel"]);
+var ORCHESTRATION_DEPTH_KEY = "__orchestration_depth";
+function strip_orchestration_tools(toolkit) {
+  return toolkit.filter((t) => !ORCHESTRATION_TOOL_NAMES.has(t.get_definition().name));
+}
+var Orchestrator = class {
+  #manager;
+  #workflow;
+  #recursive_depth;
+  /**
+   * @param source - A `WorkflowManager` or `Workflow` to spawn children from.
+   * @param options.recursive_depth - How many levels of recursive orchestration to allow. `0` (default) strips orchestration tools from children, `-1` allows unlimited nesting.
+   */
+  constructor(source, { recursive_depth = 0 } = {}) {
+    if (!Number.isInteger(recursive_depth) || recursive_depth < -1) {
+      throw new Error("invalid value for recursive_depth");
+    }
+    if (source instanceof import_core.WorkflowManager) {
+      this.#manager = source;
+    } else {
+      this.#workflow = source;
+    }
+    this.#recursive_depth = recursive_depth;
+  }
+  /**
+   * The conversation associated with the orchestrator.
+   */
+  get conversation() {
+    if (this.#manager) {
+      return this.#manager.conversation;
+    }
+    if (this.#workflow) {
+      return this.#workflow.conversation;
+    }
+    throw new Error("no source");
+  }
+  /**
+   * The parent workflow, if available. Used to establish parent-child workflow relationships.
+   */
+  get parent_workflow() {
+    if (this.#manager) {
+      return this.#manager.current_workflow;
+    }
+    return this.#workflow;
+  }
+  /**
+   * Spawn a child agent with its own conversation and workflow.
+   *
+   * Creates a child conversation, assigns tools (stripping orchestration
+   * tools when depth is exhausted), and starts the workflow. Returns a
+   * handle for awaiting, inspecting, or cancelling the child.
+   *
+   * @param prompt - The instruction to send to the child agent.
+   * @param options - Configuration for the child agent (system prompt, tools, session forking, custom ID).
+   */
+  spawn(prompt, options) {
+    const conversation = this.conversation;
+    const child = conversation.spawn_child(
+      options?.fork_session,
+      options?.id,
+      options?.system ?? conversation.system
+    );
+    const toolkit = options?.toolkit ?? [...conversation.toolkit];
+    child.toolkit = this.#recursive_depth === 0 ? strip_orchestration_tools(toolkit) : toolkit;
+    const next_depth = this.#recursive_depth === -1 ? -1 : Math.max(0, this.#recursive_depth - 1);
+    const child_context = { [ORCHESTRATION_DEPTH_KEY]: next_depth };
+    const parent = this.parent_workflow;
+    const child_workflow = parent && parent.state !== "disposed" ? parent.spawn_child(child, options?.id, child_context) : new import_core.Workflow(child, { context_data: child_context });
+    let settled = false;
+    const promise = new Promise((resolve) => {
+      child_workflow.once("workflow_end", (event) => {
+        settled = true;
+        resolve({
+          id: child_workflow.id,
+          messages: child_workflow.messages,
+          end_reason: event.reason
+        });
+        if (child.state !== "disposed") {
+          child[Symbol.dispose]();
+        }
+      });
+      try {
+        child_workflow.start();
+        child.prompt(prompt);
+      } catch {
+        if (!settled) {
+          settled = true;
+          resolve({
+            id: child_workflow.id,
+            messages: child_workflow.messages,
+            end_reason: "cancel"
+          });
+          if (child.state !== "disposed") {
+            child[Symbol.dispose]();
+          }
+        }
+      }
+    });
+    return {
+      get id() {
+        return child_workflow.id;
+      },
+      get workflow() {
+        return child_workflow;
+      },
+      promise,
+      get done() {
+        return settled;
+      },
+      cancel: () => child_workflow.cancel()
+    };
+  }
+};
+
+// src/subagent.ts
+var SubagentOrchestrator = class extends Orchestrator {
+  /**
+   * Run a prompt as an autonomous child agent and return when it completes.
+   *
+   * @param prompt - The instruction for the child agent.
+   * @param options - Configuration for the child agent (system prompt, tools, session forking, custom ID).
+   */
+  async execute(prompt, options) {
+    return this.spawn(prompt, options).promise;
+  }
+};
+
+// src/background-agent.ts
+var BackgroundOrchestrator = class extends Orchestrator {
+  #handle;
+  #status = "idle";
+  /**
+   * Start the background worker. Can only be called once.
+   *
+   * @param prompt - The instruction for the worker.
+   * @param options - Configuration for the worker (system prompt, tools, session forking, custom ID).
+   */
+  execute(prompt, options) {
+    if (this.#status !== "idle") {
+      throw new Error("invalid state");
+    }
+    this.#handle = this.spawn(prompt, options);
+    this.#status = "running";
+    this.#handle.promise.then(() => {
+      if (this.#status === "running") {
+        this.#status = "completed";
+      }
+    });
+  }
+  /**
+   * The unique identifier of this worker. Throws if not started.
+   */
+  get id() {
+    if (!this.#handle) {
+      throw new Error("not started");
+    }
+    return this.#handle.id;
+  }
+  /**
+   * Current state: `idle`, `running`, `completed`, or `cancelled`.
+   */
+  get status() {
+    return this.#status;
+  }
+  /**
+   * `true` when the worker has completed or been cancelled.
+   */
+  get done() {
+    return this.#status === "completed" || this.#status === "cancelled";
+  }
+  /**
+   * Number of agentic turns (assistant messages) so far.
+   */
+  get rounds() {
+    if (!this.#handle) {
+      return 0;
+    }
+    return this.#handle.workflow.messages.filter((m) => m.role === "assistant").length;
+  }
+  /**
+   * Total number of tool calls made across all rounds.
+   */
+  get tool_call_count() {
+    if (!this.#handle) {
+      return 0;
+    }
+    return this.#handle.workflow.messages.filter((m) => m.role === "assistant").reduce((count, m) => count + m.content.filter((c) => c.type === "tool").length, 0);
+  }
+  /**
+   * The text content of the most recent assistant message, if any.
+   */
+  get latest_message() {
+    if (!this.#handle) {
+      return void 0;
+    }
+    const messages = this.#handle.workflow.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant") {
+        const text = msg.content?.find((c) => c.type === "text");
+        if (text?.type === "text") {
+          return text.text;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Snapshot of the worker's current state.
+   */
+  get_state() {
+    if (this.#status === "idle") {
+      return {
+        id: "",
+        status: "idle",
+        rounds: 0,
+        tool_call_count: 0
+      };
+    }
+    return {
+      id: this.id,
+      status: this.#status,
+      rounds: this.rounds,
+      tool_call_count: this.tool_call_count,
+      latest_message: this.latest_message
+    };
+  }
+  /**
+   * Await completion and return the full result.
+   */
+  async collect() {
+    if (!this.#handle) {
+      throw new Error("not started");
+    }
+    return this.#handle.promise;
+  }
+  /**
+   * Cancel the running worker. Throws if not running.
+   */
+  cancel() {
+    if (this.#status !== "running" || !this.#handle) {
+      throw new Error("invalid state");
+    }
+    if (this.#handle.workflow.state !== "disposed") {
+      this.#handle.cancel();
+    }
+    this.#status = "cancelled";
+  }
+  /**
+   * Dispose the worker, cancelling it if still running.
+   */
+  [Symbol.dispose]() {
+    if (this.#status === "running" && this.#handle) {
+      if (this.#handle.workflow.state !== "disposed") {
+        this.#handle.cancel();
+      }
+      this.#status = "cancelled";
+    }
+    this.#handle = void 0;
+  }
+};
+
+// src/background-agent-pool.ts
+var BackgroundAgentPool = class {
+  #source;
+  #recursive_depth;
+  #agents = /* @__PURE__ */ new Map();
+  /**
+   * @param source - A `WorkflowManager` or `Workflow` to spawn workers from.
+   * @param options.recursive_depth - How many levels of recursive orchestration to allow in workers. Defaults to `0`.
+   */
+  constructor(source, { recursive_depth = 0 } = {}) {
+    this.#source = source;
+    this.#recursive_depth = recursive_depth;
+  }
+  /**
+   * Update the workflow/manager reference used to spawn new workers.
+   * This must be called when a persisted pool is reused by a new workflow,
+   * so that new workers are spawned from the current (live) workflow
+   * instead of a previously disposed one.
+   */
+  update_source(source) {
+    this.#source = source;
+  }
+  /**
+   * Launch a new background worker and return its ID.
+   *
+   * @param prompt - The instruction for the worker.
+   * @param options - Configuration for the worker (system prompt, tools, session forking, custom ID).
+   */
+  start(prompt, options) {
+    const agent = new BackgroundOrchestrator(this.#source, {
+      recursive_depth: this.#recursive_depth
+    });
+    agent.execute(prompt, options);
+    this.#agents.set(agent.id, agent);
+    return agent.id;
+  }
+  /**
+   * Return all worker IDs in the pool.
+   */
+  list() {
+    return [...this.#agents.keys()];
+  }
+  /**
+   * Get state snapshots for the given worker IDs, or all workers if omitted.
+   *
+   * @param ids - Worker IDs to query. Omit to query all.
+   */
+  state(...ids) {
+    const target_ids = ids.length > 0 ? ids : [...this.#agents.keys()];
+    return target_ids.map((id) => {
+      const agent = this.#agents.get(id);
+      if (!agent) {
+        throw new Error(`no worker with id ${id}`);
+      }
+      return agent.get_state();
+    });
+  }
+  /**
+   * Cancel a running worker by ID.
+   *
+   * @param id - The worker ID to cancel.
+   */
+  cancel(id) {
+    const agent = this.#agents.get(id);
+    if (!agent) {
+      throw new Error(`no worker with id ${id}`);
+    }
+    agent.cancel();
+  }
+  /**
+   * Pop completed workers from the pool and return their states. Skips workers still running.
+   *
+   * @param ids - Worker IDs to acknowledge. Omit to acknowledge all completed.
+   */
+  ack(...ids) {
+    const target_ids = ids.length > 0 ? ids : [...this.#agents.keys()];
+    const results = [];
+    for (const id of target_ids) {
+      const agent = this.#agents.get(id);
+      if (!agent) {
+        continue;
+      }
+      if (!agent.done) {
+        continue;
+      }
+      results.push(agent.get_state());
+      this.#agents.delete(id);
+    }
+    return results;
+  }
+  /**
+   * Dispose all workers in the pool, cancelling any that are still running.
+   */
+  [Symbol.dispose]() {
+    for (const agent of this.#agents.values()) {
+      agent[Symbol.dispose]();
+    }
+    this.#agents.clear();
+  }
+};
+
+// src/parallel-agent.ts
+var ParallelOrchestrator = class extends Orchestrator {
+  /**
+   * Run all tasks concurrently and return when every child agent has completed.
+   *
+   * @param tasks - Array of task configs, each with a `prompt` and optional `SubagentOptions`.
+   */
+  async execute(tasks) {
+    const handles = [];
+    try {
+      for (const { prompt, ...options } of tasks) {
+        handles.push(this.spawn(prompt, options));
+      }
+    } catch (error) {
+      for (const handle of handles) {
+        try {
+          handle.cancel();
+        } catch {
+        }
+      }
+      throw error;
+    }
+    return Promise.all(handles.map((h) => h.promise));
+  }
+};
+
+// src/tools/background-task-pool.ts
+var BackgroundTaskPoolImpl = class {
+  #pool;
+  constructor(context) {
+    const POOL_KEY = "__background_agent_pool";
+    if (!context[POOL_KEY]) {
+      const depth = context[ORCHESTRATION_DEPTH_KEY] ?? 0;
+      context[POOL_KEY] = new BackgroundAgentPool(context.workflow, { recursive_depth: depth });
+    }
+    const pool = context[POOL_KEY];
+    pool.update_source(context.workflow);
+    this.#pool = pool;
+  }
+  async execute({ action, prompts, system, fork_session, ids }) {
+    try {
+      switch (action) {
+        case "start": {
+          if (!prompts?.length) {
+            return {
+              result: false,
+              message: "prompts is required for start"
+            };
+          }
+          const started_ids = prompts.map((p) => this.#pool.start(p, { system, fork_session }));
+          return { result: true, ids: started_ids };
+        }
+        case "list": {
+          const worker_ids = this.#pool.list();
+          return { result: true, ids: worker_ids };
+        }
+        case "state": {
+          const workers = ids?.length ? this.#pool.state(...ids) : this.#pool.state();
+          return { result: true, workers };
+        }
+        case "cancel": {
+          if (!ids?.length) {
+            return {
+              result: false,
+              message: "ids is required for cancel"
+            };
+          }
+          const errors = [];
+          for (const id of ids) {
+            try {
+              this.#pool.cancel(id);
+            } catch (e) {
+              errors.push(`${id}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+          }
+          if (errors.length) {
+            return {
+              result: false,
+              message: `some cancels failed: ${errors.join("; ")}`
+            };
+          }
+          return { result: true, ids };
+        }
+        case "ack": {
+          const workers = ids?.length ? this.#pool.ack(...ids) : this.#pool.ack();
+          return { result: true, workers };
+        }
+        default: {
+          return {
+            result: false,
+            message: `unknown action: ${action}`
+          };
+        }
+      }
+    } catch (error) {
+      return {
+        result: false,
+        message: error instanceof Error ? error.message : String(error),
+        error
+      };
+    }
+  }
+  static get_definition() {
+    return {
+      name: "background",
+      description: "Manage background worker agents. Workers run independently with their own conversations and tools. Use 'start' to launch workers, 'list' to see all worker IDs, 'state' to check progress (rounds, tool calls, latest message), 'cancel' to stop workers, 'ack' to collect results from completed workers and remove them from the pool.",
+      parameters: [
+        {
+          name: "action",
+          description: "The operation to perform",
+          type: "string",
+          required: true,
+          enum: ["start", "list", "state", "cancel", "ack"]
+        },
+        {
+          name: "prompts",
+          description: "Instructions for workers to start, one per worker. Required and must not be empty when action is 'start'.",
+          type: "array",
+          required: false,
+          items: { type: "string", required: true }
+        },
+        {
+          name: "system",
+          description: "Override the system prompt (only for 'start')",
+          type: "string",
+          required: false
+        },
+        {
+          name: "fork_session",
+          description: "Start with current conversation history (only for 'start')",
+          type: "boolean",
+          required: false
+        },
+        {
+          name: "ids",
+          description: "Worker IDs to operate on (for 'state', 'cancel', 'ack'). Omit for all.",
+          type: "array",
+          required: false,
+          items: { type: "string", required: true }
+        }
+      ],
+      parallelizable: false
+    };
+  }
+};
+var BackgroundTaskPool = BackgroundTaskPoolImpl;
+
+// src/tools/utils.ts
+function extract_response(result) {
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const message = result.messages[i];
+    if (message.role !== "assistant") {
+      continue;
+    }
+    const content = message.content;
+    if (!content) {
+      continue;
+    }
+    for (let j = content.length - 1; j >= 0; j--) {
+      const block = content[j];
+      if (block.type === "text" && block.text) {
+        return block.text;
+      }
+    }
+  }
+  return "(no text response)";
+}
+
+// src/tools/parallel-agent-task.ts
+var ParallelAgentTaskImpl = class {
+  #agent;
+  constructor(context) {
+    const depth = context[ORCHESTRATION_DEPTH_KEY] ?? 0;
+    this.#agent = new ParallelOrchestrator(context.workflow, { recursive_depth: depth });
+  }
+  async execute({ prompts, system, fork_session }) {
+    try {
+      if (!prompts?.length) {
+        return {
+          result: false,
+          message: "prompts is required and must not be empty"
+        };
+      }
+      const tasks = prompts.map((prompt) => ({ prompt, system, fork_session }));
+      const results = await this.#agent.execute(tasks);
+      return {
+        result: true,
+        responses: results.map((r) => ({
+          id: r.id,
+          response: extract_response(r),
+          end_reason: r.end_reason
+        }))
+      };
+    } catch (error) {
+      return {
+        result: false,
+        message: error instanceof Error ? error.message : String(error),
+        error
+      };
+    }
+  }
+  static get_definition() {
+    return {
+      name: "parallel",
+      description: "Run multiple prompts as concurrent sub-agents. All agents start immediately and the tool returns when every agent has completed. Each sub-agent has its own conversation and access to the same tools. Use when tasks are independent and can benefit from concurrent execution.",
+      parameters: [
+        {
+          name: "prompts",
+          description: "Array of instructions, one per sub-agent",
+          type: "array",
+          required: true,
+          items: { type: "string", required: true }
+        },
+        {
+          name: "system",
+          description: "Override the system prompt for all sub-agents",
+          type: "string",
+          required: false
+        },
+        {
+          name: "fork_session",
+          description: "If true, each sub-agent starts with the current conversation history",
+          type: "boolean",
+          required: false
+        }
+      ],
+      parallelizable: false
+    };
+  }
+};
+var ParallelAgentTask = ParallelAgentTaskImpl;
+
+// src/tools/subagent-task.ts
+var SubagentTaskImpl = class {
+  #agent;
+  constructor(context) {
+    const depth = context[ORCHESTRATION_DEPTH_KEY] ?? 0;
+    this.#agent = new SubagentOrchestrator(context.workflow, { recursive_depth: depth });
+  }
+  async execute({ prompt, system, fork_session }) {
+    try {
+      const result = await this.#agent.execute(prompt, { system, fork_session });
+      return {
+        result: true,
+        id: result.id,
+        response: extract_response(result),
+        end_reason: result.end_reason
+      };
+    } catch (error) {
+      return {
+        result: false,
+        message: error instanceof Error ? error.message : String(error),
+        error
+      };
+    }
+  }
+  static get_definition() {
+    return {
+      name: "subagent",
+      description: "Run a prompt as an autonomous sub-agent with its own conversation. The sub-agent has access to the same tools and runs to completion, returning its final response. Use for tasks that require independent multi-step reasoning or tool use.",
+      parameters: [
+        {
+          name: "prompt",
+          description: "The instruction for the sub-agent",
+          type: "string",
+          required: true
+        },
+        {
+          name: "system",
+          description: "Override the system prompt for this sub-agent",
+          type: "string",
+          required: false
+        },
+        {
+          name: "fork_session",
+          description: "If true, the sub-agent starts with a copy of the current conversation history",
+          type: "boolean",
+          required: false
+        }
+      ],
+      parallelizable: true
+    };
+  }
+};
+var SubagentTask = SubagentTaskImpl;
+
+// src/tools/index.ts
+var OrchestrationToolkit = [
+  SubagentTask,
+  ParallelAgentTask,
+  BackgroundTaskPool
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BackgroundAgentPool,
+  BackgroundOrchestrator,
+  BackgroundTaskPool,
+  ORCHESTRATION_DEPTH_KEY,
+  OrchestrationToolkit,
+  Orchestrator,
+  ParallelAgentTask,
+  ParallelOrchestrator,
+  SubagentOrchestrator,
+  SubagentTask
+});
+//# sourceMappingURL=index.cjs.map