@simulacra-ai/orchestration 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -1,8 +1,342 @@
-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
+import { ToolClass, Workflow, Message, WorkflowManager, Conversation, ToolSuccessResult } from '@simulacra-ai/core';
+
+/**
+ * Configuration options for spawning a subagent.
+ */
+interface SubagentOptions {
+    /**
+     * The system prompt for the subagent's conversation.
+     */
+    system?: string;
+    /**
+     * The tools available to the subagent.
+     */
+    toolkit?: ToolClass[];
+    /**
+     * Whether the subagent starts with a copy of the parent's conversation history.
+     */
+    fork_session?: boolean;
+    /**
+     * A custom identifier for the subagent.
+     */
+    id?: string;
+}
+/**
+ * The result of a completed subagent execution.
+ */
+interface SubagentResult {
+    /**
+     * The unique identifier of the subagent.
+     */
+    id: string;
+    /**
+     * The complete message history from the subagent's conversation.
+     */
+    messages: readonly Readonly<Message>[];
+    /**
+     * The reason the subagent's execution ended.
+     */
+    end_reason: "complete" | "cancel" | "error";
+}
+/**
+ * A handle for managing a background subagent task.
+ */
+interface BackgroundHandle {
+    /**
+     * The unique identifier of the background task.
+     */
+    readonly id: string;
+    /**
+     * The workflow instance running the background task.
+     */
+    readonly workflow: Workflow;
+    /**
+     * A promise that resolves when the background task completes.
+     */
+    readonly promise: Promise<SubagentResult>;
+    /**
+     * Whether the background task has finished execution.
+     */
+    readonly done: boolean;
+    /**
+     * Cancels the background task.
+     */
+    cancel(): void;
+}
+/**
+ * Status snapshot of a background worker.
+ */
+interface WorkerState {
+    /**
+     * The unique identifier of the worker.
+     */
+    id: string;
+    /**
+     * The worker's current execution state.
+     */
+    status: "idle" | "running" | "completed" | "cancelled";
+    /**
+     * Number of agentic turns (assistant messages) completed.
+     */
+    rounds: number;
+    /**
+     * Total number of tool calls made across all rounds.
+     */
+    tool_call_count: number;
+    /**
+     * The text content of the most recent assistant message, if any.
+     */
+    latest_message?: string;
+}
+
+/**
+ * Context key used to propagate the remaining orchestration depth to child agents.
+ */
+declare const ORCHESTRATION_DEPTH_KEY = "__orchestration_depth";
+/**
+ * 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, `recursive_depth` is `0`, which strips orchestration tools
+ * from child agents to prevent nesting. Set to a positive number to allow
+ * that many levels of recursive orchestration, or `-1` for unlimited depth.
+ */
+declare abstract class Orchestrator {
+    #private;
+    /**
+     * @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: WorkflowManager | Workflow, { recursive_depth }?: {
+        recursive_depth?: number | 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 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).
+     */
+    protected spawn(prompt: string, options?: SubagentOptions): BackgroundHandle;
+}
+
+/**
+ * Spawns a child agent and blocks until it completes.
+ *
+ * The child runs its own agentic loop with access to the parent's tools.
+ * Orchestration tools are excluded when `recursive_depth` is 0 (the default)
+ * and included when a positive depth is configured.
+ */
+declare class SubagentOrchestrator 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).
+     */
+    execute(prompt: string, options?: SubagentOptions): Promise<SubagentResult>;
+}
+
+/**
+ * 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.
+ */
+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(): "idle" | "running" | "completed" | "cancelled";
+    /**
+     * `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;
+}
+
+/**
+ * Manages a pool of background worker agents.
+ *
+ * Provides a registry for starting, listing, inspecting, cancelling,
+ * and acknowledging (collecting + removing) completed workers.
+ */
+declare class BackgroundAgentPool {
+    #private;
+    /**
+     * @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: WorkflowManager | Workflow, { recursive_depth }?: {
+        recursive_depth?: number | undefined;
+    });
+    /**
+     * 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;
+}
+
+/**
+ * Runs multiple prompts concurrently, each as an independent child agent.
+ * Returns when all complete.
+ */
+declare class ParallelOrchestrator 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`.
+     */
+    execute(tasks: Array<{
+        prompt: string;
+    } & SubagentOptions>): Promise<SubagentResult[]>;
+}
+
+type BackgroundParams = {
+    action: "start" | "list" | "state" | "cancel" | "ack";
+    prompts?: string[];
+    system?: string;
+    fork_session?: boolean;
+    ids?: string[];
+};
+type BackgroundToolSuccess = ToolSuccessResult & {
+    ids?: string[];
+    workers?: WorkerState[];
+};
+/**
+ * Tool that lets a model manage a pool of background worker agents. Supports
+ * starting tasks, listing workers, checking state, cancelling, and collecting
+ * results without blocking the main conversation.
+ */
+declare const BackgroundTaskPool: ToolClass<BackgroundParams, BackgroundToolSuccess>;
+
+type ParallelParams = {
+    prompts: string[];
+    system?: string;
+    fork_session?: boolean;
+};
+type ParallelToolSuccess = ToolSuccessResult & {
+    responses: Array<{
+        id: string;
+        response: string;
+        end_reason: string;
+    }>;
+};
+/**
+ * Tool that lets a model run multiple subtasks concurrently, each handled by its
+ * own subagent with a separate conversation. All subagents start immediately and
+ * the tool returns once every subagent has completed.
+ */
+declare const ParallelAgentTask: ToolClass<ParallelParams, ParallelToolSuccess>;
+
+type SubagentParams = {
+    prompt: string;
+    system?: string;
+    fork_session?: boolean;
+};
+type SubagentToolSuccess = ToolSuccessResult & {
+    id: string;
+    response: string;
+    end_reason: string;
+};
+/**
+ * Tool that lets a model spawn an autonomous subagent with its own conversation
+ * to handle a subtask independently. The subagent runs to completion and returns
+ * its final response.
+ */
+declare const SubagentTask: ToolClass<SubagentParams, SubagentToolSuccess>;
+
+/**
+ * All orchestration tools as a ready-to-use toolkit.
+ */
+declare const OrchestrationToolkit: ToolClass[];
+
+export { BackgroundAgentPool, type BackgroundHandle, BackgroundOrchestrator, BackgroundTaskPool, ORCHESTRATION_DEPTH_KEY, OrchestrationToolkit, Orchestrator, ParallelAgentTask, ParallelOrchestrator, type SubagentOptions, SubagentOrchestrator, type SubagentResult, SubagentTask, type WorkerState };