@simulacra-ai/orchestration 0.0.3 → 0.0.4

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/orchestrator.ts","../src/subagent.ts","../src/background-agent.ts","../src/background-agent-pool.ts","../src/parallel-agent.ts","../src/tools/background-task-pool.ts","../src/tools/utils.ts","../src/tools/parallel-agent-task.ts","../src/tools/subagent-task.ts","../src/tools/index.ts"],"sourcesContent":["export * from \"./types.ts\";\nexport * from \"./orchestrator.ts\";\nexport * from \"./subagent.ts\";\nexport * from \"./background-agent.ts\";\nexport * from \"./background-agent-pool.ts\";\nexport * from \"./parallel-agent.ts\";\nexport * from \"./tools/index.ts\";\n","import { Workflow, WorkflowManager } from \"@simulacra-ai/core\";\nimport type { Conversation, ToolClass } from \"@simulacra-ai/core\";\nimport type { BackgroundHandle, SubagentOptions, SubagentResult } from \"./types.ts\";\n\nconst ORCHESTRATION_TOOL_NAMES = new Set([\"subagent\", \"background\", \"parallel\"]);\n\n/**\n * Context key used to propagate the remaining orchestration depth to child agents.\n */\nexport const ORCHESTRATION_DEPTH_KEY = \"__orchestration_depth\";\n\n/**\n * Remove orchestration tools from a toolkit to prevent child agents from nesting.\n *\n * @param toolkit - The toolkit to filter.\n */\nfunction strip_orchestration_tools(toolkit: ToolClass[]): ToolClass[] {\n  return toolkit.filter((t) => !ORCHESTRATION_TOOL_NAMES.has(t.get_definition().name));\n}\n\n/**\n * Base class for orchestration patterns.\n *\n * Accepts a `WorkflowManager` (for programmatic use) or a `Workflow`\n * (for tool integration). Provides the shared child-spawning logic\n * that all orchestration patterns build on.\n *\n * By default, `recursive_depth` is `0`, which strips orchestration tools\n * from child agents to prevent nesting. Set to a positive number to allow\n * that many levels of recursive orchestration, or `-1` for unlimited depth.\n */\nexport abstract class Orchestrator {\n  readonly #manager?: WorkflowManager;\n  readonly #workflow?: Workflow;\n  readonly #recursive_depth: number;\n\n  /**\n   * @param source - A `WorkflowManager` or `Workflow` to spawn children from.\n   * @param options.recursive_depth - How many levels of recursive orchestration to allow. `0` (default) strips orchestration tools from children, `-1` allows unlimited nesting.\n   */\n  constructor(source: WorkflowManager | Workflow, { recursive_depth = 0 } = {}) {\n    if (!Number.isInteger(recursive_depth) || recursive_depth < -1) {\n      throw new Error(\"invalid value for recursive_depth\");\n    }\n    if (source instanceof WorkflowManager) {\n      this.#manager = source;\n    } else {\n      this.#workflow = source;\n    }\n    this.#recursive_depth = recursive_depth;\n  }\n\n  /**\n   * The conversation associated with the orchestrator.\n   */\n  protected get conversation(): Conversation {\n    if (this.#manager) {\n      return this.#manager.conversation;\n    }\n    if (this.#workflow) {\n      return this.#workflow.conversation;\n    }\n    throw new Error(\"no source\");\n  }\n\n  /**\n   * The parent workflow, if available. Used to establish parent-child workflow relationships.\n   */\n  protected get parent_workflow(): Workflow | undefined {\n    if (this.#manager) {\n      return this.#manager.current_workflow;\n    }\n    return this.#workflow;\n  }\n\n  /**\n   * Spawn a child agent with its own conversation and workflow.\n   *\n   * Creates a child conversation, assigns tools (stripping orchestration\n   * tools when depth is exhausted), and starts the workflow. Returns a\n   * handle for awaiting, inspecting, or cancelling the child.\n   *\n   * @param prompt - The instruction to send to the child agent.\n   * @param options - Configuration for the child agent (system prompt, tools, session forking, custom ID).\n   */\n  protected spawn(prompt: string, options?: SubagentOptions): BackgroundHandle {\n    const conversation = this.conversation;\n    const child = conversation.spawn_child(\n      options?.fork_session,\n      options?.id,\n      options?.system ?? conversation.system,\n    );\n    const toolkit = options?.toolkit ?? [...conversation.toolkit];\n    child.toolkit = this.#recursive_depth === 0 ? strip_orchestration_tools(toolkit) : toolkit;\n\n    const next_depth = this.#recursive_depth === -1 ? -1 : Math.max(0, this.#recursive_depth - 1);\n    const child_context = { [ORCHESTRATION_DEPTH_KEY]: next_depth };\n\n    const parent = this.parent_workflow;\n    const child_workflow =\n      parent && parent.state !== \"disposed\"\n        ? parent.spawn_child(child, options?.id, child_context)\n        : new Workflow(child, { context_data: child_context });\n\n    let settled = false;\n\n    const promise = new Promise<SubagentResult>((resolve) => {\n      child_workflow.once(\"workflow_end\", (event) => {\n        settled = true;\n        resolve({\n          id: child_workflow.id,\n          messages: child_workflow.messages,\n          end_reason: event.reason,\n        });\n        if (child.state !== \"disposed\") {\n          child[Symbol.dispose]();\n        }\n      });\n\n      try {\n        child_workflow.start();\n        child.prompt(prompt);\n      } catch {\n        if (!settled) {\n          settled = true;\n          resolve({\n            id: child_workflow.id,\n            messages: child_workflow.messages,\n            end_reason: \"cancel\",\n          });\n          if (child.state !== \"disposed\") {\n            child[Symbol.dispose]();\n          }\n        }\n      }\n    });\n\n    return {\n      get id() {\n        return child_workflow.id;\n      },\n      get workflow() {\n        return child_workflow;\n      },\n      promise,\n      get done() {\n        return settled;\n      },\n      cancel: () => child_workflow.cancel(),\n    };\n  }\n}\n","import { Orchestrator } from \"./orchestrator.ts\";\nimport type { SubagentOptions, SubagentResult } from \"./types.ts\";\n\n/**\n * Spawns a child agent and blocks until it completes.\n *\n * The child runs its own agentic loop with access to the parent's tools.\n * Orchestration tools are excluded when `recursive_depth` is 0 (the default)\n * and included when a positive depth is configured.\n */\nexport class SubagentOrchestrator extends Orchestrator {\n  /**\n   * Run a prompt as an autonomous child agent and return when it completes.\n   *\n   * @param prompt - The instruction for the child agent.\n   * @param options - Configuration for the child agent (system prompt, tools, session forking, custom ID).\n   */\n  async execute(prompt: string, options?: SubagentOptions): Promise<SubagentResult> {\n    return this.spawn(prompt, options).promise;\n  }\n}\n","import { Orchestrator } from \"./orchestrator.ts\";\nimport type { BackgroundHandle, SubagentOptions, SubagentResult, WorkerState } from \"./types.ts\";\n\n/**\n * A single background worker agent.\n *\n * Each instance represents one background task. Call `execute` once to\n * start it, then use `status`, `done`, `collect`, and `cancel` to manage it.\n */\nexport class BackgroundOrchestrator extends Orchestrator {\n  #handle?: BackgroundHandle;\n  #status: \"idle\" | \"running\" | \"completed\" | \"cancelled\" = \"idle\";\n\n  /**\n   * Start the background worker. Can only be called once.\n   *\n   * @param prompt - The instruction for the worker.\n   * @param options - Configuration for the worker (system prompt, tools, session forking, custom ID).\n   */\n  execute(prompt: string, options?: SubagentOptions): void {\n    if (this.#status !== \"idle\") {\n      throw new Error(\"invalid state\");\n    }\n    this.#handle = this.spawn(prompt, options);\n    this.#status = \"running\";\n    this.#handle.promise.then(() => {\n      if (this.#status === \"running\") {\n        this.#status = \"completed\";\n      }\n    });\n  }\n\n  /**\n   * The unique identifier of this worker. Throws if not started.\n   */\n  get id(): string {\n    if (!this.#handle) {\n      throw new Error(\"not started\");\n    }\n    return this.#handle.id;\n  }\n\n  /**\n   * Current state: `idle`, `running`, `completed`, or `cancelled`.\n   */\n  get status() {\n    return this.#status;\n  }\n\n  /**\n   * `true` when the worker has completed or been cancelled.\n   */\n  get done(): boolean {\n    return this.#status === \"completed\" || this.#status === \"cancelled\";\n  }\n\n  /**\n   * Number of agentic turns (assistant messages) so far.\n   */\n  get rounds(): number {\n    if (!this.#handle) {\n      return 0;\n    }\n    return this.#handle.workflow.messages.filter((m) => m.role === \"assistant\").length;\n  }\n\n  /**\n   * Total number of tool calls made across all rounds.\n   */\n  get tool_call_count(): number {\n    if (!this.#handle) {\n      return 0;\n    }\n    return this.#handle.workflow.messages\n      .filter((m) => m.role === \"assistant\")\n      .reduce((count, m) => count + m.content.filter((c) => c.type === \"tool\").length, 0);\n  }\n\n  /**\n   * The text content of the most recent assistant message, if any.\n   */\n  get latest_message(): string | undefined {\n    if (!this.#handle) {\n      return undefined;\n    }\n    const messages = this.#handle.workflow.messages;\n    for (let i = messages.length - 1; i >= 0; i--) {\n      const msg = messages[i];\n      if (msg.role === \"assistant\") {\n        const text = msg.content?.find((c) => c.type === \"text\");\n        if (text?.type === \"text\") {\n          return text.text;\n        }\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * Snapshot of the worker's current state.\n   */\n  get_state(): WorkerState {\n    if (this.#status === \"idle\") {\n      return {\n        id: \"\",\n        status: \"idle\",\n        rounds: 0,\n        tool_call_count: 0,\n      };\n    }\n    return {\n      id: this.id,\n      status: this.#status,\n      rounds: this.rounds,\n      tool_call_count: this.tool_call_count,\n      latest_message: this.latest_message,\n    };\n  }\n\n  /**\n   * Await completion and return the full result.\n   */\n  async collect(): Promise<SubagentResult> {\n    if (!this.#handle) {\n      throw new Error(\"not started\");\n    }\n    return this.#handle.promise;\n  }\n\n  /**\n   * Cancel the running worker. Throws if not running.\n   */\n  cancel(): void {\n    if (this.#status !== \"running\" || !this.#handle) {\n      throw new Error(\"invalid state\");\n    }\n    if (this.#handle.workflow.state !== \"disposed\") {\n      this.#handle.cancel();\n    }\n    this.#status = \"cancelled\";\n  }\n\n  /**\n   * Dispose the worker, cancelling it if still running.\n   */\n  [Symbol.dispose](): void {\n    if (this.#status === \"running\" && this.#handle) {\n      if (this.#handle.workflow.state !== \"disposed\") {\n        this.#handle.cancel();\n      }\n      this.#status = \"cancelled\";\n    }\n    this.#handle = undefined;\n  }\n}\n","import type { Workflow, WorkflowManager } from \"@simulacra-ai/core\";\nimport { BackgroundOrchestrator } from \"./background-agent.ts\";\nimport type { SubagentOptions, WorkerState } from \"./types.ts\";\n\n/**\n * Manages a pool of background worker agents.\n *\n * Provides a registry for starting, listing, inspecting, cancelling,\n * and acknowledging (collecting + removing) completed workers.\n */\nexport class BackgroundAgentPool {\n  #source: WorkflowManager | Workflow;\n  readonly #recursive_depth: number;\n  readonly #agents = new Map<string, BackgroundOrchestrator>();\n\n  /**\n   * @param source - A `WorkflowManager` or `Workflow` to spawn workers from.\n   * @param options.recursive_depth - How many levels of recursive orchestration to allow in workers. Defaults to `0`.\n   */\n  constructor(source: WorkflowManager | Workflow, { recursive_depth = 0 } = {}) {\n    this.#source = source;\n    this.#recursive_depth = recursive_depth;\n  }\n\n  /**\n   * Update the workflow/manager reference used to spawn new workers.\n   * This must be called when a persisted pool is reused by a new workflow,\n   * so that new workers are spawned from the current (live) workflow\n   * instead of a previously disposed one.\n   */\n  update_source(source: WorkflowManager | Workflow): void {\n    this.#source = source;\n  }\n\n  /**\n   * Launch a new background worker and return its ID.\n   *\n   * @param prompt - The instruction for the worker.\n   * @param options - Configuration for the worker (system prompt, tools, session forking, custom ID).\n   */\n  start(prompt: string, options?: SubagentOptions): string {\n    const agent = new BackgroundOrchestrator(this.#source, {\n      recursive_depth: this.#recursive_depth,\n    });\n    agent.execute(prompt, options);\n    this.#agents.set(agent.id, agent);\n    return agent.id;\n  }\n\n  /**\n   * Return all worker IDs in the pool.\n   */\n  list(): string[] {\n    return [...this.#agents.keys()];\n  }\n\n  /**\n   * Get state snapshots for the given worker IDs, or all workers if omitted.\n   *\n   * @param ids - Worker IDs to query. Omit to query all.\n   */\n  state(...ids: string[]): WorkerState[] {\n    const target_ids = ids.length > 0 ? ids : [...this.#agents.keys()];\n    return target_ids.map((id) => {\n      const agent = this.#agents.get(id);\n      if (!agent) {\n        throw new Error(`no worker with id ${id}`);\n      }\n      return agent.get_state();\n    });\n  }\n\n  /**\n   * Cancel a running worker by ID.\n   *\n   * @param id - The worker ID to cancel.\n   */\n  cancel(id: string): void {\n    const agent = this.#agents.get(id);\n    if (!agent) {\n      throw new Error(`no worker with id ${id}`);\n    }\n    agent.cancel();\n  }\n\n  /**\n   * Pop completed workers from the pool and return their states. Skips workers still running.\n   *\n   * @param ids - Worker IDs to acknowledge. Omit to acknowledge all completed.\n   */\n  ack(...ids: string[]): WorkerState[] {\n    const target_ids = ids.length > 0 ? ids : [...this.#agents.keys()];\n    const results: WorkerState[] = [];\n    for (const id of target_ids) {\n      const agent = this.#agents.get(id);\n      if (!agent) {\n        continue;\n      }\n      if (!agent.done) {\n        continue;\n      }\n      results.push(agent.get_state());\n      this.#agents.delete(id);\n    }\n    return results;\n  }\n\n  /**\n   * Dispose all workers in the pool, cancelling any that are still running.\n   */\n  [Symbol.dispose](): void {\n    for (const agent of this.#agents.values()) {\n      agent[Symbol.dispose]();\n    }\n    this.#agents.clear();\n  }\n}\n","import { Orchestrator } from \"./orchestrator.ts\";\nimport type { BackgroundHandle, SubagentOptions, SubagentResult } from \"./types.ts\";\n\n/**\n * Runs multiple prompts concurrently, each as an independent child agent.\n * Returns when all complete.\n */\nexport class ParallelOrchestrator extends Orchestrator {\n  /**\n   * Run all tasks concurrently and return when every child agent has completed.\n   *\n   * @param tasks - Array of task configs, each with a `prompt` and optional `SubagentOptions`.\n   */\n  async execute(tasks: Array<{ prompt: string } & SubagentOptions>): Promise<SubagentResult[]> {\n    const handles: BackgroundHandle[] = [];\n    try {\n      for (const { prompt, ...options } of tasks) {\n        handles.push(this.spawn(prompt, options));\n      }\n    } catch (error) {\n      for (const handle of handles) {\n        try {\n          handle.cancel();\n        } catch {\n          /* ignore */\n        }\n      }\n      throw error;\n    }\n    return Promise.all(handles.map((h) => h.promise));\n  }\n}\n","import type {\n  Tool,\n  ToolClass,\n  ToolContext,\n  ToolDefinition,\n  ToolErrorResult,\n  ToolSuccessResult,\n} from \"@simulacra-ai/core\";\nimport { BackgroundAgentPool } from \"../background-agent-pool.ts\";\nimport { ORCHESTRATION_DEPTH_KEY } from \"../orchestrator.ts\";\nimport type { WorkerState } from \"../types.ts\";\n\ntype BackgroundParams = {\n  action: \"start\" | \"list\" | \"state\" | \"cancel\" | \"ack\";\n  prompts?: string[];\n  system?: string;\n  fork_session?: boolean;\n  ids?: string[];\n};\n\ntype BackgroundToolSuccess = ToolSuccessResult & {\n  ids?: string[];\n  workers?: WorkerState[];\n};\n\nclass BackgroundTaskPoolImpl implements Tool<BackgroundParams, BackgroundToolSuccess> {\n  readonly #pool: BackgroundAgentPool;\n\n  constructor(context: ToolContext) {\n    const POOL_KEY = \"__background_agent_pool\";\n    if (!context[POOL_KEY]) {\n      const depth = (context[ORCHESTRATION_DEPTH_KEY] as number) ?? 0;\n      context[POOL_KEY] = new BackgroundAgentPool(context.workflow, { recursive_depth: depth });\n    }\n    const pool = context[POOL_KEY] as BackgroundAgentPool;\n    pool.update_source(context.workflow);\n    this.#pool = pool;\n  }\n\n  async execute({ action, prompts, system, fork_session, ids }: BackgroundParams) {\n    try {\n      switch (action) {\n        case \"start\": {\n          if (!prompts?.length) {\n            return {\n              result: false as const,\n              message: \"prompts is required for start\",\n            } as ToolErrorResult;\n          }\n          const started_ids = prompts.map((p) => this.#pool.start(p, { system, fork_session }));\n          return { result: true as const, ids: started_ids };\n        }\n        case \"list\": {\n          const worker_ids = this.#pool.list();\n          return { result: true as const, ids: worker_ids };\n        }\n        case \"state\": {\n          const workers = ids?.length ? this.#pool.state(...ids) : this.#pool.state();\n          return { result: true as const, workers };\n        }\n        case \"cancel\": {\n          if (!ids?.length) {\n            return {\n              result: false as const,\n              message: \"ids is required for cancel\",\n            } as ToolErrorResult;\n          }\n          const errors: string[] = [];\n          for (const id of ids) {\n            try {\n              this.#pool.cancel(id);\n            } catch (e) {\n              errors.push(`${id}: ${e instanceof Error ? e.message : String(e)}`);\n            }\n          }\n          if (errors.length) {\n            return {\n              result: false as const,\n              message: `some cancels failed: ${errors.join(\"; \")}`,\n            } as ToolErrorResult;\n          }\n          return { result: true as const, ids };\n        }\n        case \"ack\": {\n          const workers = ids?.length ? this.#pool.ack(...ids) : this.#pool.ack();\n          return { result: true as const, workers };\n        }\n        default: {\n          return {\n            result: false as const,\n            message: `unknown action: ${action}`,\n          } as ToolErrorResult;\n        }\n      }\n    } catch (error) {\n      return {\n        result: false as const,\n        message: error instanceof Error ? error.message : String(error),\n        error,\n      } as ToolErrorResult;\n    }\n  }\n\n  static get_definition(): ToolDefinition {\n    return {\n      name: \"background\",\n      description:\n        \"Manage background worker agents. Workers run independently with their own \" +\n        \"conversations and tools. Use 'start' to launch workers, 'list' to see all \" +\n        \"worker IDs, 'state' to check progress (rounds, tool calls, latest message), \" +\n        \"'cancel' to stop workers, 'ack' to collect results from completed workers \" +\n        \"and remove them from the pool.\",\n      parameters: [\n        {\n          name: \"action\",\n          description: \"The operation to perform\",\n          type: \"string\",\n          required: true,\n          enum: [\"start\", \"list\", \"state\", \"cancel\", \"ack\"],\n        },\n        {\n          name: \"prompts\",\n          description:\n            \"Instructions for workers to start, one per worker. Required and must not be empty when action is 'start'.\",\n          type: \"array\",\n          required: false,\n          items: { type: \"string\", required: true },\n        },\n        {\n          name: \"system\",\n          description: \"Override the system prompt (only for 'start')\",\n          type: \"string\",\n          required: false,\n        },\n        {\n          name: \"fork_session\",\n          description: \"Start with current conversation history (only for 'start')\",\n          type: \"boolean\",\n          required: false,\n        },\n        {\n          name: \"ids\",\n          description: \"Worker IDs to operate on (for 'state', 'cancel', 'ack'). Omit for all.\",\n          type: \"array\",\n          required: false,\n          items: { type: \"string\", required: true },\n        },\n      ],\n      parallelizable: false,\n    };\n  }\n}\n\n/**\n * Tool that lets a model manage a pool of background worker agents. Supports\n * starting tasks, listing workers, checking state, cancelling, and collecting\n * results without blocking the main conversation.\n */\nexport const BackgroundTaskPool: ToolClass<BackgroundParams, BackgroundToolSuccess> =\n  BackgroundTaskPoolImpl;\n","import type { SubagentResult } from \"../types.ts\";\n\n/**\n * Extract the final text response from a subagent result.\n *\n * @param result - The completed subagent result.\n */\nexport function extract_response(result: SubagentResult): string {\n  for (let i = result.messages.length - 1; i >= 0; i--) {\n    const message = result.messages[i];\n    if (message.role !== \"assistant\") {\n      continue;\n    }\n    const content = message.content;\n    if (!content) {\n      continue;\n    }\n    for (let j = content.length - 1; j >= 0; j--) {\n      const block = content[j];\n      if (block.type === \"text\" && block.text) {\n        return block.text;\n      }\n    }\n  }\n  return \"(no text response)\";\n}\n","import type {\n  Tool,\n  ToolClass,\n  ToolContext,\n  ToolDefinition,\n  ToolErrorResult,\n  ToolSuccessResult,\n} from \"@simulacra-ai/core\";\nimport { ORCHESTRATION_DEPTH_KEY } from \"../orchestrator.ts\";\nimport { ParallelOrchestrator } from \"../parallel-agent.ts\";\nimport { extract_response } from \"./utils.ts\";\n\ntype ParallelParams = {\n  prompts: string[];\n  system?: string;\n  fork_session?: boolean;\n};\n\ntype ParallelToolSuccess = ToolSuccessResult & {\n  responses: Array<{\n    id: string;\n    response: string;\n    end_reason: string;\n  }>;\n};\n\nclass ParallelAgentTaskImpl implements Tool<ParallelParams, ParallelToolSuccess> {\n  readonly #agent: ParallelOrchestrator;\n\n  constructor(context: ToolContext) {\n    const depth = (context[ORCHESTRATION_DEPTH_KEY] as number) ?? 0;\n    this.#agent = new ParallelOrchestrator(context.workflow, { recursive_depth: depth });\n  }\n\n  async execute({ prompts, system, fork_session }: ParallelParams) {\n    try {\n      if (!prompts?.length) {\n        return {\n          result: false as const,\n          message: \"prompts is required and must not be empty\",\n        } as ToolErrorResult;\n      }\n      const tasks = prompts.map((prompt) => ({ prompt, system, fork_session }));\n      const results = await this.#agent.execute(tasks);\n      return {\n        result: true as const,\n        responses: results.map((r) => ({\n          id: r.id,\n          response: extract_response(r),\n          end_reason: r.end_reason,\n        })),\n      };\n    } catch (error) {\n      return {\n        result: false as const,\n        message: error instanceof Error ? error.message : String(error),\n        error,\n      } as ToolErrorResult;\n    }\n  }\n\n  static get_definition(): ToolDefinition {\n    return {\n      name: \"parallel\",\n      description:\n        \"Run multiple prompts as concurrent sub-agents. All agents start immediately \" +\n        \"and the tool returns when every agent has completed. Each sub-agent has its \" +\n        \"own conversation and access to the same tools. Use when tasks are independent \" +\n        \"and can benefit from concurrent execution.\",\n      parameters: [\n        {\n          name: \"prompts\",\n          description: \"Array of instructions, one per sub-agent\",\n          type: \"array\",\n          required: true,\n          items: { type: \"string\", required: true },\n        },\n        {\n          name: \"system\",\n          description: \"Override the system prompt for all sub-agents\",\n          type: \"string\",\n          required: false,\n        },\n        {\n          name: \"fork_session\",\n          description: \"If true, each sub-agent starts with the current conversation history\",\n          type: \"boolean\",\n          required: false,\n        },\n      ],\n      parallelizable: false,\n    };\n  }\n}\n\n/**\n * Tool that lets a model run multiple subtasks concurrently, each handled by its\n * own subagent with a separate conversation. All subagents start immediately and\n * the tool returns once every subagent has completed.\n */\nexport const ParallelAgentTask: ToolClass<ParallelParams, ParallelToolSuccess> =\n  ParallelAgentTaskImpl;\n","import type {\n  Tool,\n  ToolClass,\n  ToolContext,\n  ToolDefinition,\n  ToolErrorResult,\n  ToolSuccessResult,\n} from \"@simulacra-ai/core\";\nimport { ORCHESTRATION_DEPTH_KEY } from \"../orchestrator.ts\";\nimport { SubagentOrchestrator } from \"../subagent.ts\";\nimport { extract_response } from \"./utils.ts\";\n\ntype SubagentParams = {\n  prompt: string;\n  system?: string;\n  fork_session?: boolean;\n};\n\ntype SubagentToolSuccess = ToolSuccessResult & {\n  id: string;\n  response: string;\n  end_reason: string;\n};\n\nclass SubagentTaskImpl implements Tool<SubagentParams, SubagentToolSuccess> {\n  readonly #agent: SubagentOrchestrator;\n\n  constructor(context: ToolContext) {\n    const depth = (context[ORCHESTRATION_DEPTH_KEY] as number) ?? 0;\n    this.#agent = new SubagentOrchestrator(context.workflow, { recursive_depth: depth });\n  }\n\n  async execute({ prompt, system, fork_session }: SubagentParams) {\n    try {\n      const result = await this.#agent.execute(prompt, { system, fork_session });\n      return {\n        result: true as const,\n        id: result.id,\n        response: extract_response(result),\n        end_reason: result.end_reason,\n      };\n    } catch (error) {\n      return {\n        result: false as const,\n        message: error instanceof Error ? error.message : String(error),\n        error,\n      } as ToolErrorResult;\n    }\n  }\n\n  static get_definition(): ToolDefinition {\n    return {\n      name: \"subagent\",\n      description:\n        \"Run a prompt as an autonomous sub-agent with its own conversation. \" +\n        \"The sub-agent has access to the same tools and runs to completion, \" +\n        \"returning its final response. Use for tasks that require independent \" +\n        \"multi-step reasoning or tool use.\",\n      parameters: [\n        {\n          name: \"prompt\",\n          description: \"The instruction for the sub-agent\",\n          type: \"string\",\n          required: true,\n        },\n        {\n          name: \"system\",\n          description: \"Override the system prompt for this sub-agent\",\n          type: \"string\",\n          required: false,\n        },\n        {\n          name: \"fork_session\",\n          description:\n            \"If true, the sub-agent starts with a copy of the current conversation history\",\n          type: \"boolean\",\n          required: false,\n        },\n      ],\n      parallelizable: true,\n    };\n  }\n}\n\n/**\n * Tool that lets a model spawn an autonomous subagent with its own conversation\n * to handle a subtask independently. The subagent runs to completion and returns\n * its final response.\n */\nexport const SubagentTask: ToolClass<SubagentParams, SubagentToolSuccess> = SubagentTaskImpl;\n","import type { ToolClass } from \"@simulacra-ai/core\";\nexport { BackgroundTaskPool } from \"./background-task-pool.ts\";\nexport { ParallelAgentTask } from \"./parallel-agent-task.ts\";\nexport { SubagentTask } from \"./subagent-task.ts\";\nimport { BackgroundTaskPool } from \"./background-task-pool.ts\";\nimport { ParallelAgentTask } from \"./parallel-agent-task.ts\";\nimport { SubagentTask } from \"./subagent-task.ts\";\n\n/**\n * All orchestration tools as a ready-to-use toolkit.\n */\nexport const OrchestrationToolkit: ToolClass[] = [\n  SubagentTask,\n  ParallelAgentTask,\n  BackgroundTaskPool,\n];\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,342 @@
+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 };