Crate sacp_conductor

Crate sacp_conductor 

Source
Expand description

§sacp-conductor

Binary for orchestrating ACP proxy chains.

§What is the conductor?

The conductor is a tool that manages proxy chains - it spawns proxy components and the base agent, then routes messages between them. From the editor’s perspective, the conductor appears as a single ACP agent.

Editor ← stdio → Conductor → Proxy 1 → Proxy 2 → Agent

§Usage

§Agent Mode

Orchestrate a chain of proxies in front of an agent:

# Chain format: proxy1 proxy2 ... agent
sacp-conductor agent "python proxy1.py" "python proxy2.py" "python base-agent.py"

The conductor:

  1. Spawns each component as a subprocess
  2. Connects them in a chain
  3. Presents as a single agent on stdin/stdout
  4. Manages the lifecycle of all processes

§MCP Bridge Mode

Connect stdio to a TCP-based MCP server:

# Bridge stdio to MCP server on localhost:8080
sacp-conductor mcp 8080

This allows stdio-based tools to communicate with TCP MCP servers.

§How It Works

Component Communication:

  • Editor talks to conductor via stdio
  • Conductor uses _proxy/successor/* protocol extensions to route messages
  • Each proxy can intercept, transform, or forward messages
  • Final agent receives standard ACP messages

Process Management:

  • All components are spawned as child processes
  • When conductor exits, all children are terminated
  • Errors in any component bring down the entire chain

§Example Use Case

Add Sparkle embodiment + custom tools to any agent:

sacp-conductor agent \
  "sparkle-acp-proxy" \
  "my-custom-tools-proxy" \
  "claude-agent"

This creates a stack where:

  1. Sparkle proxy injects MCP servers and prepends embodiment
  2. Custom tools proxy adds domain-specific functionality
  3. Base agent handles the actual AI responses
  • sacp-proxy - Framework for building proxy components
  • sacp - Core ACP SDK
  • sacp-tokio - Tokio utilities for process spawning

Modules§

trace
Trace event types for sequence diagram viewer Trace event types for the sequence diagram viewer.

Structs§

AgentOnly
Wrapper to convert a single agent component (no proxies) into InstantiateProxiesAndAgent.
CommandLineComponents
Wrapper for command-line component lists that can serve as either proxies-only (for proxy mode) or proxies+agent (for agent mode).
Conductor
The conductor manages the proxy chain lifecycle and message routing.
ConductorArgs
ConductorResponder
The conductor manages the proxy chain lifecycle and message routing.
ProxiesAndAgent
Builder for creating proxies and agent components.

Enums§

ConductorCommand
ConductorMessage
Messages sent to the conductor’s main event loop for routing.
McpBridgeMode
Mode for the MCP bridge.
SourceComponentIndex
Identifies the source of an agent-to-client message.

Traits§

ConductorLink
Trait implemented for the two links the conductor can use:
ConductorSuccessor
InstantiateProxies
Trait for lazy proxy instantiation (proxy mode).
InstantiateProxiesAndAgent
Trait for lazy proxy and agent instantiation (agent mode).
JrResponseExt