bamboo-broker 2026.7.21

Standalone network message broker for sub-agent ask/reply: durable Mailbox queues fronted by a WebSocket bus
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

//! `bamboo-broker` — a standalone network message broker for sub-agent
//! ask/reply (and future task/handoff) traffic.
//!
//! The broker fronts durable per-session [`Mailbox`](bamboo_subagent::Mailbox)
//! queues with a WebSocket bus, so a central orchestrator and its workers —
//! local subprocesses, local Docker containers, or SSH/remote hosts — exchange
//! messages over the network with durability and at-least-once delivery, without
//! sharing a filesystem.
//!
//! Topology: a single central broker (hub-and-spoke). It is a *pure message
//! bus* — it routes messages, it does not spawn actors or coordinate with other
//! brokers. Spawning the PUSH-side workers lives in [`deploy`] (the `Deployer`
//! family: local / docker / ssh / russh). (The `bamboo_subagent::WorkerLauncher`
//! trait that earlier docs referenced was never wired and has been removed; the
//! PULL-side actor runner dispatches placement inline.)
//!
//! Layers:
//! - [`proto`] — the client↔broker wire frames.
//! - [`core`] — [`BrokerCore`], the transport-agnostic routing engine (tested in-process).
//! - the WebSocket server + auth + `bamboo broker serve` wiring layer on top (added next).

pub mod ask;
pub mod child_link;
pub mod client;
pub mod core;
pub mod deploy;
pub mod deploy_russh;
pub mod mcp;
pub mod mux;
pub mod proto;
pub mod serve;
pub mod server;

mod error;

/// The orchestrator's broker mailbox id — where workers send MCP proxy requests
/// and where `serve_mcp_proxy` listens. A fixed well-known id (single MCP host).
pub const ORCHESTRATOR_ID: &str = "bamboo-orchestrator";

pub use crate::ask::{ask_agent, ask_over, request_over};
pub use crate::child_link::BrokerChildLink;
pub use crate::client::{client_config_trusting_cert, BrokerClient};
pub use crate::core::{BrokerCore, DEFAULT_MAX_PENDING_PER_MAILBOX};
pub use crate::deploy::{
    AgentDeployment, DeployedAgent, Deployer, DockerDeployer, LocalProcessDeployer,
    RemoteDeployment, SshDeployer, UploadSpec,
};
pub use crate::deploy_russh::{RusshAuth, RusshDeployer};
pub use crate::error::{BrokerError, BrokerResult};
pub use crate::mcp::{
    serve_mcp_proxy, serve_mcp_proxy_supervised, McpProxyExecutor, McpReply, McpRequest,
    ProxiedResult, RoleToolAllowlist,
};
pub use crate::mux::MultiplexedClient;
pub use crate::proto::{BrokerFrame, ClientFrame};
pub use crate::serve::{
    serve_executor, serve_executor_full, serve_executor_with_shutdown, serve_loop, serve_mailbox,
    serve_mailbox_full, serve_mailbox_with_shutdown, serve_with, Handled,
};
pub use crate::server::{BrokerLimits, BrokerServer};
pub use bamboo_subagent::AgentRef;