dirigate/README.md

Dirigate

ACP (Agent-Client Protocol) bridge and mock server for testing and proxying ACP connections.

Overview

dirigate provides tools for working with ACP clients and servers:

1. Bridge Mode: Relay stdio ACP clients to a Dirigent ACP Server via HTTP/SSE
2. Mock Server: Serve fixture-based responses for testing ACP clients
3. Interactive Client: Connect to ACP agents for debugging and exploration

Features

• Bridge Mode: Connect external ACP clients (like Claude Code) to a Dirigent ACP Server
• Fixture-based responses: Define sessions and message flows in YAML for testing
• Multiple response modes: Static, random, sequential, and pattern-based
• Session ingestion: Import sessions from OpenCode.ai or other sources (feature-gated)
• ACP compliance: Full protocol implementation for testing clients
• CLI tool: Easy-to-use command-line interface

Installation

As a CLI Tool

cargo install --path packages/conductor

As a Library

Add to your Cargo.toml:

[dependencies]
conductor = { path = "../conductor" }

For ingestion features:

[dependencies]
conductor = { path = "../conductor", features = ["ingest"] }

Usage

Bridge Mode (NEW)

Bridge a stdio ACP client to a Dirigent ACP Server via HTTP/SSE:

# Connect to local server (default: http://localhost:3001/acp)
conductor bridge

# Connect to remote server
conductor bridge --server-url http://remote:3001/acp

# Via environment variable
DIRIGENT_SERVER_URL=http://remote:3001/acp dirigate bridge

# With verbose logging
conductor bridge --verbose

Bridge Architecture:

External ACP Client (Claude Code, etc.)
    |
    | stdio (stdin/stdout)
    v
+-------------------+
| Conductor Bridge  |
| - stdin parser    |
| - HTTP client     |
| - SSE subscriber  |
+-------------------+
    |
    | HTTP/SSE
    v
Dirigent ACP Server

Options:

• -s, --server-url <URL> - ACP Server URL (env: DIRIGENT_SERVER_URL, default: http://localhost:3001/acp)
• -v, --verbose - Enable verbose logging of JSON-RPC messages
• --timeout <SECS> - Timeout for HTTP requests (default: 30)
• --auto-reconnect - Automatically reconnect SSE stream on disconnect (default: true)

Use Case: Connecting Claude Code to Dirigent

To use Claude Code with Dirigent:

1. Start the Dirigent web application (which includes the ACP Server)
2. Configure Claude Code to use a command-based ACP agent:

   dirigate bridge
   

3. Claude Code will now communicate through Conductor to Dirigent

Mock Server

conductor serve --fixtures ./fixtures --port 8080

Options:

• -f, --fixtures <DIR> - Directory containing fixture YAML files (default: ./fixtures)
• -p, --port <PORT> - Port to bind the server to (default: 8080)
• --host <HOST> - Host address to bind to (default: 127.0.0.1)
• --stdio - Use stdin/stdout for JSON-RPC transport
• -l, --log-level <LEVEL> - Log level: trace, debug, info, warn, error (default: info)
• --log-format <FORMAT> - Log format: pretty, json, compact (default: pretty)

Validate Fixtures

conductor validate ./fixtures

Validates fixture files without starting the server.

Interactive Client

Connect to an ACP agent for debugging and exploration:

# Connect via stdio (spawns a process)
conductor connect --command "claude --acp" --auto-session

# Connect via HTTP
conductor connect --url http://localhost:8080 --auto-session

# Custom protocol version
conductor connect --command "claude --acp" --protocol-version 1 --auto-session

Interactive Commands:

• /help - Display available commands
• /quit - Exit the client
• /session list - List available sessions
• /session new - Create a new session
• /session <id> - Switch to a session
• /cancel - Cancel generation in current session
• Any other text - Send as message to current session

Debugging:

Enable detailed logging to see JSON-RPC packets:

# See all debug logs including packets
RUST_LOG=debug dirigate connect --command "claude --acp" --auto-session

# See event details
DIRIGENT_VERBOSE=1 dirigate connect --command "claude --acp" --auto-session

Ingest Sessions (requires ingest feature)

conductor ingest \
  -u http://localhost:12225 \
  --session-id my-session-123 \
  --output ./fixtures/my-session.yaml

Imports a session from an external source and converts it to fixture format.

Fixture Format

Fixtures are defined in YAML files:

version: "1"

streaming:
  enabled: true
  tokens_per_chunk: 4
  chunk_interval_ms: 50

sessions:
  - id: "session-123"
    title: "Test Session"
    created_at: "2025-01-01T00:00:00Z"
    participants:
      - id: "assistant"
        name: "Assistant"
        role: "agent"
    messages:
      - role: "agent"
        content: "Hello! How can I help you?"

responders:
  default_strategy: Echo
  keyword_map: {}

Response Modes

• sequential: Return messages in order (default)
• random: Return a random message from the fixture
• pattern: Match user input against patterns and return corresponding response
• static: Always return the same message
• echo: Echo back the user's input

Project Structure

conductor/
|-- src/
|   |-- lib.rs              # Library entry point
|   |-- error.rs            # Error types
|   |-- logging.rs          # Logging infrastructure
|   |-- acp/                # ACP protocol implementation
|   |   |-- mod.rs
|   |   |-- bridge.rs       # Bridge mode (stdio <-> HTTP/SSE)
|   |   |-- server.rs       # HTTP server
|   |   |-- model.rs        # Protocol types
|   |   |-- stdio.rs        # Stdio transport
|   |   |-- stream.rs       # SSE streaming
|   |-- fixture/            # Fixture system
|   |   |-- mod.rs
|   |   |-- types.rs        # Fixture definitions
|   |   |-- loader.rs       # YAML loading
|   |   |-- responders.rs   # Response logic
|   |-- ingest/             # Session ingestion (feature-gated)
|   |   |-- mod.rs
|   |   |-- opencode.rs     # OpenCode.ai ingestion
|   |-- cli/                # CLI interface
|   |   |-- mod.rs
|   |   |-- args.rs         # Argument parsing
|   |   |-- commands.rs     # Command execution
|   |-- bin/
|       |-- conductor.rs  # Binary entry point
|-- Cargo.toml
|-- README.md

Configuration

Environment Variables

Variable	Description	Default
DIRIGENT_SERVER_URL	ACP Server URL for bridge mode	http://localhost:3001/acp
CONDUCTOR_BUFFER_SIZE	Broadcast channel buffer size for event distribution. Increase for high-volume event scenarios or when experiencing event drops during bursts. Valid values: Any positive integer (usize). Example: CONDUCTOR_BUFFER_SIZE=500	100
RUST_LOG	Log level	info
DIRIGENT_VERBOSE	Enable verbose event logging	(unset)

Testing

Run tests:

cargo test -p dirigate

Run with all features:

cargo test -p dirigate --all-features

Dependencies

Core

• clap - CLI argument parsing
• serde, serde_yaml, serde_json - Serialization
• tokio - Async runtime
• axum - Web server
• reqwest - HTTP client (for bridge mode)
• reqwest-eventsource - SSE client (for bridge mode)
• anyhow, thiserror - Error handling
• tracing, tracing-subscriber - Logging

Optional (ingest feature)

• dirigent_protocol - Protocol types
• opencode_client - OpenCode.ai client

License

Same as the Dirigent project.

Contributing

See the main project README for contribution guidelines.