@simulacra-ai/orchestration 0.0.1

package/README.md

@@ -0,0 +1,123 @@
+# Simulacra Agent Orchestration
+
+Multi-agent orchestration patterns for the Simulacra conversation engine. Child agents run independently with their own conversations and tool access.
+
+## Installation
+
+```bash
+npm install @simulacra-ai/core @simulacra-ai/orchestration
+```
+
+## Setup
+
+All orchestration patterns require a `WorkflowManager` wrapping a conversation with tools:
+
+```typescript
+import { Conversation, WorkflowManager } from "@simulacra-ai/core";
+
+const conversation = new Conversation(provider);
+conversation.toolkit = [/* your tools */];
+const workflowManager = new WorkflowManager(conversation);
+```
+
+## Usage
+
+### SubagentOrchestrator
+
+Spawns a child agent and blocks until it completes.
+
+```typescript
+import { SubagentOrchestrator } from "@simulacra-ai/orchestration";
+
+const agent = new SubagentOrchestrator(workflowManager);
+const result = await agent.execute("Analyze this data and report findings");
+
+console.log(result.end_reason); // "complete" | "cancel" | "error"
+console.log(result.messages);
+```
+
+### BackgroundOrchestrator
+
+A single background worker. Call `execute` once to start, then inspect or collect.
+
+```typescript
+import { BackgroundOrchestrator } from "@simulacra-ai/orchestration";
+
+using worker = new BackgroundOrchestrator(workflowManager);
+worker.execute("Monitor the feed for changes");
+
+// later
+worker.status; // "running" | "completed" | "cancelled"
+worker.done; // true when completed or cancelled
+worker.rounds; // number of agentic turns
+worker.tool_call_count; // total tool calls made
+worker.latest_message; // last assistant text
+
+const result = await worker.collect(); // await completion, get full result
+worker.cancel(); // cancel if still running
+// automatically disposed at end of scope
+```
+
+### BackgroundAgentPool
+
+Manages multiple background workers with batch operations.
+
+```typescript
+import { BackgroundAgentPool } from "@simulacra-ai/orchestration";
+
+using pool = new BackgroundAgentPool(workflowManager);
+
+const id1 = pool.start("Research topic A");
+const id2 = pool.start("Research topic B");
+const id3 = pool.start("Research topic C");
+
+pool.list(); // [id1, id2, id3]
+pool.state(id1, id2); // WorkerState[] with status, rounds, tool_call_count, latest_message
+pool.cancel(id2); // cancel a specific worker
+
+const done = pool.ack(); // pop all completed workers, returns their states
+// all remaining workers cancelled and cleaned up at end of scope
+```
+
+### ParallelOrchestrator
+
+Runs multiple prompts concurrently and waits for all to complete.
+
+```typescript
+import { ParallelOrchestrator } from "@simulacra-ai/orchestration";
+
+const agent = new ParallelOrchestrator(workflowManager);
+const results = await agent.execute([
+  { prompt: "Analyze dataset A" },
+  { prompt: "Analyze dataset B" },
+  { prompt: "Analyze dataset C", system: "Focus on outliers" },
+]);
+```
+
+## LLM Tools
+
+Each pattern is available as a `ToolClass` for model-driven orchestration.
+
+> **Note:** By default, orchestration tools are stripped from child agents to prevent recursive nesting. Pass `strip_tools: false` to the `Orchestrator` constructor to allow it.
+
+```typescript
+import { OrchestrationToolkit } from "@simulacra-ai/orchestration";
+
+conversation.toolkit = [...conversation.toolkit, ...OrchestrationToolkit];
+```
+
+Individual tools (`SubagentTask`, `BackgroundWorkerPool`, `ParallelAgentTask`) are also exported if you want to pick selectively.
+
+`BackgroundWorkerPool` exposes a worker pool to the model with these actions:
+
+Action|Description
+-|-
+`start`|Launch one or more background workers (requires `prompts`)
+`list`|List all worker IDs
+`state`|Get status, rounds, tool calls, latest message (optional `ids`)
+`cancel`|Stop workers (requires `ids`)
+`ack`|Pop completed workers and return their states (optional `ids`)
+
+## License
+
+MIT

package/dist/background-agent-pool.d.ts

@@ -0,0 +1,56 @@
+import type { Workflow, WorkflowManager } from "@simulacra-ai/core";
+import type { SubagentOptions, WorkerState } from "./types.ts";
+/**
+ * Manages a pool of background worker agents.
+ *
+ * Provides a registry for starting, listing, inspecting, cancelling,
+ * and acknowledging (collecting + removing) completed workers.
+ */
+export declare class BackgroundAgentPool {
+    #private;
+    /**
+     * @param source - A `WorkflowManager` or `Workflow` to spawn workers from.
+     */
+    constructor(source: WorkflowManager | Workflow);
+    /**
+     * 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: WorkflowManager | Workflow): void;
+    /**
+     * 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: string, options?: SubagentOptions): string;
+    /**
+     * Return all worker IDs in the pool.
+     */
+    list(): string[];
+    /**
+     * 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: string[]): WorkerState[];
+    /**
+     * Cancel a running worker by ID.
+     *
+     * @param id - The worker ID to cancel.
+     */
+    cancel(id: string): void;
+    /**
+     * 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: string[]): WorkerState[];
+    /**
+     * Dispose all workers in the pool, cancelling any that are still running.
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=background-agent-pool.d.ts.map

package/dist/background-agent-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-agent-pool.d.ts","sourceRoot":"","sources":["../src/background-agent-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,mBAAmB;;IAI9B;;OAEG;gBACS,MAAM,EAAE,eAAe,GAAG,QAAQ;IAI9C;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,GAAG,IAAI;IAIvD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM;IAOxD;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACH,KAAK,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE;IAWtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQxB;;;;OAIG;IACH,GAAG,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE;IAiBpC;;OAEG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAMzB"}

package/dist/background-agent-pool.js

@@ -0,0 +1,102 @@
+import { BackgroundOrchestrator } from "./background-agent.js";
+/**
+ * Manages a pool of background worker agents.
+ *
+ * Provides a registry for starting, listing, inspecting, cancelling,
+ * and acknowledging (collecting + removing) completed workers.
+ */
+export class BackgroundAgentPool {
+    #source;
+    #agents = new Map();
+    /**
+     * @param source - A `WorkflowManager` or `Workflow` to spawn workers from.
+     */
+    constructor(source) {
+        this.#source = source;
+    }
+    /**
+     * 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);
+        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();
+    }
+}
+//# sourceMappingURL=background-agent-pool.js.map

package/dist/background-agent-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-agent-pool.js","sourceRoot":"","sources":["../src/background-agent-pool.ts"],"names":[],"mappings":"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"}

package/dist/background-agent.d.ts

@@ -0,0 +1,59 @@
+import { Orchestrator } from "./orchestrator.ts";
+import type { SubagentOptions, SubagentResult, WorkerState } from "./types.ts";
+/**
+ * A single background worker agent.
+ *
+ * Each instance represents one background task. Call `execute` once to
+ * start it, then use `status`, `done`, `collect`, and `cancel` to manage it.
+ */
+export declare class BackgroundOrchestrator extends Orchestrator {
+    #private;
+    /**
+     * 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: string, options?: SubagentOptions): void;
+    /**
+     * The unique identifier of this worker. Throws if not started.
+     */
+    get id(): string;
+    /**
+     * Current state: `idle`, `running`, `completed`, or `cancelled`.
+     */
+    get status(): "running" | "completed" | "cancelled" | "idle";
+    /**
+     * `true` when the worker has completed or been cancelled.
+     */
+    get done(): boolean;
+    /**
+     * Number of agentic turns (assistant messages) so far.
+     */
+    get rounds(): number;
+    /**
+     * Total number of tool calls made across all rounds.
+     */
+    get tool_call_count(): number;
+    /**
+     * The text content of the most recent assistant message, if any.
+     */
+    get latest_message(): string | undefined;
+    /**
+     * Snapshot of the worker's current state.
+     */
+    get_state(): WorkerState;
+    /**
+     * Await completion and return the full result.
+     */
+    collect(): Promise<SubagentResult>;
+    /**
+     * Cancel the running worker. Throws if not running.
+     */
+    cancel(): void;
+    /**
+     * Dispose the worker, cancelling it if still running.
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=background-agent.d.ts.map

package/dist/background-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-agent.d.ts","sourceRoot":"","sources":["../src/background-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAoB,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjG;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;;IAItD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI;IAaxD;;OAEG;IACH,IAAI,EAAE,IAAI,MAAM,CAKf;IAED;;OAEG;IACH,IAAI,MAAM,mDAET;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAKnB;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAO5B;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAevC;IAED;;OAEG;IACH,SAAS,IAAI,WAAW;IAUxB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAOxC;;OAEG;IACH,MAAM,IAAI,IAAI;IAUd;;OAEG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CASzB"}

package/dist/background-agent.js

@@ -0,0 +1,135 @@
+import { Orchestrator } from "./orchestrator.js";
+/**
+ * A single background worker agent.
+ *
+ * Each instance represents one background task. Call `execute` once to
+ * start it, then use `status`, `done`, `collect`, and `cancel` to manage it.
+ */
+export class BackgroundOrchestrator 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 undefined;
+        }
+        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 undefined;
+    }
+    /**
+     * Snapshot of the worker's current state.
+     */
+    get_state() {
+        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 = undefined;
+    }
+}
+//# sourceMappingURL=background-agent.js.map

package/dist/background-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-agent.js","sourceRoot":"","sources":["../src/background-agent.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.ts";
+export * from "./orchestrator.ts";
+export * from "./subagent.ts";
+export * from "./background-agent.ts";
+export * from "./background-agent-pool.ts";
+export * from "./parallel-agent.ts";
+export * from "./tools/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./orchestrator.js";
+export * from "./subagent.js";
+export * from "./background-agent.js";
+export * from "./background-agent-pool.js";
+export * from "./parallel-agent.js";
+export * from "./tools/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/orchestrator.d.ts

@@ -0,0 +1,43 @@
+import { Workflow, WorkflowManager } from "@simulacra-ai/core";
+import type { Conversation } from "@simulacra-ai/core";
+import type { BackgroundHandle, SubagentOptions } from "./types.ts";
+/**
+ * Base class for orchestration patterns.
+ *
+ * Accepts a `WorkflowManager` (for programmatic use) or a `Workflow`
+ * (for tool integration). Provides the shared child-spawning logic
+ * that all orchestration patterns build on.
+ *
+ * By default, orchestration tools are stripped from child agents to
+ * prevent nesting. Pass `strip_tools: false` to allow it.
+ */
+export declare abstract class Orchestrator {
+    #private;
+    /**
+     * @param source - A `WorkflowManager` or `Workflow` to spawn children from.
+     * @param options.strip_tools - Remove orchestration tools from child agents. Defaults to `true`.
+     */
+    constructor(source: WorkflowManager | Workflow, { strip_tools }?: {
+        strip_tools?: boolean | undefined;
+    });
+    /**
+     * The conversation associated with the orchestrator.
+     */
+    protected get conversation(): Conversation;
+    /**
+     * The parent workflow, if available. Used to establish parent-child workflow relationships.
+     */
+    protected get parent_workflow(): Workflow | undefined;
+    /**
+     * Spawn a child agent with its own conversation and workflow.
+     *
+     * Creates a child conversation, assigns tools (stripping orchestration
+     * tools unless disabled), 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).
+     */
+    protected spawn(prompt: string, options?: SubagentOptions): BackgroundHandle;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAC;AAapF;;;;;;;;;GASG;AACH,8BAAsB,YAAY;;IAKhC;;;OAGG;gBACS,MAAM,EAAE,eAAe,GAAG,QAAQ,EAAE,EAAE,WAAkB,EAAE;;KAAK;IAS3E;;OAEG;IACH,SAAS,KAAK,YAAY,IAAI,YAAY,CAQzC;IAED;;OAEG;IACH,SAAS,KAAK,eAAe,IAAI,QAAQ,GAAG,SAAS,CAKpD;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,gBAAgB;CA+D7E"}