@thinkwell/conductor

TypeScript conductor for ACP proxy chains.

Overview

The conductor orchestrates message routing between clients, proxies, and agents in the Agent Client Protocol (ACP). It sits between every component, managing process lifecycle and message flow.

``
Client <-> Conductor <-> [Proxy 0] <-> [Proxy 1] <-> ... <-> Agent
`

Installation

`bash
pnpm add @thinkwell/conductor
`

Usage

$3

`typescript
import { Conductor, fromCommands, ChannelConnector } from '@thinkwell/conductor';

// Create a conductor that spawns an agent subprocess
const conductor = new Conductor({
instantiator: fromCommands(['my-agent']),
});

// Connect a client
const clientConnector = new ChannelConnector(/ your channel /);
await conductor.connect(clientConnector);
`

$3

`typescript
const conductor = new Conductor({
// Last command is the agent, earlier commands are proxies
instantiator: fromCommands(['my-proxy', 'my-agent']),
});
`

$3

`typescript
const conductor = new Conductor({
instantiator: fromCommands(['my-agent']),
logging: {
level: 'debug', // 'error' | 'warn' | 'info' | 'debug' | 'trace'
name: 'my-app',
json: true, // Output as JSON for machine parsing
},
});
`

$3

Write all messages to a JSONL file for debugging:

`typescript
const conductor = new Conductor({
instantiator: fromCommands(['my-agent']),
trace: {
path: '/tmp/conductor-trace.jsonl',
},
});
`

Each line in the trace file is a JSON object with:
- timestamp: ISO 8601 timestamp
- direction: 'left-to-right' | 'right-to-left' | 'internal'
- source: Source component identifier
- target: Target component identifier
- message: The full ConductorMessage object

$3

`typescript
import { Conductor, dynamic, StdioConnector } from '@thinkwell/conductor';

const conductor = new Conductor({
instantiator: dynamic(async (initRequest) => {
// Inspect the initialize request to decide what to spawn
const needsProxy = initRequest.params?.mcpServers?.length > 0;

return {
proxies: needsProxy ? [new StdioConnector('my-proxy')] : [],
agent: new StdioConnector('my-agent'),
};
}),
});
`

API Reference

$3

Main class that orchestrates the proxy chain.

#### Constructor Options

| Option | Type | Description |
|--------|------|-------------|
| name | string | Optional name for debugging |
| instantiator | ComponentInstantiator | Creates components on initialization |
| mcpBridgeMode | 'http' \| 'disabled' | MCP bridge mode (default: 'http') |
| logging | LoggerOptions | Logging configuration |
| trace | TraceOptions | JSONL trace output configuration |

#### Methods

- connect(clientConnector): Connect to a client and run the message loop
- shutdown(): Shut down the conductor and all components

$3

Factory functions for creating component configurations:

- fromCommands(commands): Create from a list of command strings (last is agent)
- fromConnectors({ proxies, agent }): Create from explicit connectors
- staticInstantiator(config): Create with detailed options
- dynamic(factory): Create dynamically based on initialize request

$3

- StdioConnector: Spawns a subprocess and communicates via stdin/stdout
- ChannelConnector: In-memory channel for testing

$3

- createLogger(options): Create a logger instance
- createNoopLogger(): Create a logger that discards all output
- getLogger(): Get the default logger
- setLogger(logger)`: Set the default logger

License

See repository root for license information.