@robota-sdk/agent-subagent-runner

Child-process subagent runner for the Robota SDK. Runs subagents in isolated child processes with IPC, worktree isolation, and log streaming.

Installation

pnpm add @robota-sdk/agent-subagent-runner

Overview

This package is an optional add-on for @robota-sdk/agent-framework. It enables spawning subagents in separate Node.js child processes, giving each subagent full process isolation while maintaining structured IPC communication back to the parent session.

agent-cli
  └── createChildProcessSubagentRunnerFactory()
        └── ChildProcessSubagentRunner  ← this package
              ├── fork()                ← Node.js child_process.fork
              ├── IPC messages          ← TSubagentWorkerParentMessage / TSubagentWorkerChildMessage
              └── worktree isolation    ← via agent-executor

Usage

import { createChildProcessSubagentRunnerFactory } from '@robota-sdk/agent-subagent-runner';

const factory = createChildProcessSubagentRunnerFactory({
  providerConfig,
  logsDir,
  // workerPath is optional — defaults to the bundled worker entry point
});

Pass factory to createAgentRuntime({ subagentRunnerFactory: factory }).

API

Functions

| Export | Description | | -------------------------------------------------- | --------------------------------------------------------------------------- | | createChildProcessSubagentRunnerFactory(options) | Returns a TSubagentRunnerFactory that spawns subagents in child processes | | getDefaultSubagentWorkerPath() | Resolves the path to the bundled worker entry point |

Classes

| Export | Description | | ---------------------------- | ------------------------------------------------------- | | ChildProcessSubagentRunner | Implements ISubagentRunner using child_process.fork |

Types

| Export | Description | | ------------------------------------ | ----------------------------------------------------- | | IChildProcessSubagentRunnerOptions | Options for createChildProcessSubagentRunnerFactory | | ISubagentWorkerStartPayload | IPC payload sent from parent to worker on start | | TSubagentWorkerParentMessage | Union of all messages the parent sends to the worker | | TSubagentWorkerChildMessage | Union of all messages the worker sends to the parent | | TSubagentWorkerWireValue | Serializable value type used in IPC messages |

Type Guards

| Export | Description | | ------------------------------- | ----------------------------------------- | | isSubagentWorkerParentMessage | Narrows to TSubagentWorkerParentMessage | | isSubagentWorkerChildMessage | Narrows to TSubagentWorkerChildMessage |

Dependencies

• @robota-sdk/agent-executor — worktree isolation and background task primitives
• @robota-sdk/agent-framework — runtime types (ISubagentRunner, TSubagentRunnerFactory)

License

MIT