Honeydipper’s internal communication is built around an eventbus — a message bus that routes messages between services (engine, operator, receiver, agent, API) and external drivers. Each message has a
ChannelandSubjectthat determine its routing.
The eventbus is Honeydipper’s nervous system. All inter-service communication flows through it:
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Receiver │────►│ Engine │────►│ Operator │
│ │ │ │ │ │
└──────────┘ └────┬─────┘ └────┬─────┘
│ │
eventbus:return eventbus:command
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Engine │ │ Operator │────► Drivers
│(continue)│ │(execute) │
└──────────┘ └──────────┘
┌──────────┐ ┌──────────┐
│ API │◄───►│ Agent │────► AI Drivers
│ (HTTP) │ │ Service │ (agentbus)
└──────────┘ └──────────┘
Messages are routed by their Channel and Subject. The eventbus driver (typically Redis-based) handles the actual message delivery.
The core message type is defined in pkg/dipper/comm.go:
type Message struct {
Channel string // Routing channel (e.g., "eventbus", "rpc")
Subject string // Message subject/type (e.g., "message", "command")
Labels map[string]string // Metadata for routing, tracking, and context
Payload interface{} // Message data (arbitrary JSON-serializable content)
}
| Field | Type | Description |
|---|---|---|
Channel |
string |
High-level routing channel. Core channels: eventbus, rpc, command, state, agentbus. |
Subject |
string |
Specific message type within the channel. Combined with channel as channel:subject for routing. |
Labels |
map[string]string |
Key-value metadata. Used for session tracking (sessionID, agent_session_id), routing hints (feature, method), status reporting (status, reason), and context propagation. |
Payload |
interface{} |
The actual message data. Structure varies by subject type. |
| Channel | Constant | Description |
|---|---|---|
eventbus |
dipper.ChannelEventbus |
Primary inter-service and service-to-driver event channel. |
rpc |
dipper.ChannelRPC |
RPC-style request/reply calls. |
command |
dipper.ChannelCommand |
Command execution channel (service-to-driver). |
state |
dipper.ChannelState |
State persistence channel. |
agentbus |
"agentbus" |
Agent service to/from AI model drivers. |
These are the core eventbus subjects defined in pkg/dipper/comm.go:
| Subject | Constant | Direction | Description |
|---|---|---|---|
message |
dipper.EventbusMessage |
→ Engine | Incoming event from a driver (triggered by external source). |
command |
dipper.EventbusCommand |
→ Operator | Function execution request. The operator resolves the target system/function and calls the appropriate driver. |
agent_command |
dipper.EventbusAgentCommand |
→ Operator | Agent tool call execution request. Same as command but for agent tool invocations. |
return |
dipper.EventbusReturn |
→ Engine | Function execution result. Contains the output of a completed system function or workflow step. |
return/interrupted |
dipper.EventbusReturnInterrupted |
→ Operator | Interrupted function notification. The operator re-queues the message for retry. |
agent_continue |
dipper.EventbusAgentContinue |
→ Engine | Agent tool call result. Returns tool execution output to the agent service for session continuation. |
The agent service uses these subjects for AI model interaction and session management (defined in internal/service/agent_svc.go):
| Subject | Direction | Description |
|---|---|---|
agent_start |
Store → Agent Service | Initiates a new inference session. Contains resume_key for workflow callback and agent_name label. |
agent_continue |
Operator/Engine → Agent Service | Delivers tool call results back to an existing session. |
agent_recover |
Store → Agent Service | Recovers an interrupted session after daemon restart. Carries agent_session_id from the RPC interrupted notification. |
agent_poll |
Workflow/UI → Agent Service | Polls a session for new streaming output (full messages and/or pending chunks). |
agent_call |
Agent Service Store | Dispatches a sub-agent invocation. Carries sub_agent_name, input, agent_session_id. |
mcp_call |
Agent Service Store | Dispatches a remote MCP tool call. Carries server, tool, args. |
convo_cancel |
API/UI → Agent Service | Marks a conversation as cancelled. |
Agentbus subjects (used between agent service and AI model drivers via RPC):
| Subject | Direction | Description |
|---|---|---|
agentbus:receive |
AI Driver → Agent Service | Model inference result delivered to the agent service. |
agentbus:rpc/interrupted |
AI Driver → Agent Service | Notification that a model’s RPC context was cancelled mid-inference. |
| Subject | Direction | Description |
|---|---|---|
rpc:call |
Internal | RPC method invocation. |
rpc:return |
Internal | RPC method result. |
rpc/interrupted |
Internal | RPC call was interrupted (e.g., context cancelled). |
| Subject | Description |
|---|---|
broadcast:reload |
Configuration reload signal. All services reload their configuration. |
| Subject | Direction | Description |
|---|---|---|
api-broadcast |
API → All | Broadcast API requests to matching services. |
api:candidate |
Internal | API lock contention resolution. |
eventbus:api |
→ API Service | API messages received from the eventbus (ACKs and results). |
| Subject | Direction | Description |
|---|---|---|
scheduler:session |
→ Engine | Scheduled session tick. Triggers time-based workflow execution. |
A complete agent inference session follows this message flow:
Workflow/UI ──eventbus:resume_key──► Agent Service
(agent_svc.go:handleAgentStart)
Labels: {
"resume_key": "<uuid>",
"agent_name": "my_assistant"
}
Payload: {
"text": "user message",
"type": "chat_turn" | "inference",
"data": { ... },
"user": "alice@example.com"
}
The agent service emits an agent_response immediately:
{
"channel": "eventbus",
"subject": "agent_response",
"labels": {
"resume_key": "<uuid>",
"agent_session_id": "<session-uuid>"
}
}
The agent session sends to the AI driver via RPC:
Agent Service ──► driver:<driver_name>.send_to_model
(agentbus:receive on return)
Parameters: {
"engine": "gpt-4o",
"history": [ ... ],
"tools": [ ... ],
"type": "chat_turn",
"model_data": { ... },
"should_stream": true,
"agent_settings": { ... }
}
Labels: {
"agent_session_id": "<session-uuid>",
"timeout": "1h"
}
AI Driver ──agentbus:receive──► Agent Service
(agent_svc.go:handleAgentReceive)
Payload: {
"message": {
"role": "agent",
"content": "response text",
"tool_calls": [ ... ],
"is_complete": true
}
}
Labels: {
"agent_session_id": "<session-uuid>",
"status": "success" | "failure",
"reason": "<error message>"
}
When the model requests tool calls, the agent session dispatches based on prefix:
| Tool Prefix | Eventbus Subject | Direction |
|---|---|---|
sys_* |
eventbus:agent_command |
→ Operator |
wf__* |
eventbus:agent_workflow |
→ Engine |
ag__* |
eventbus:agent_call |
→ Agent Service (Store) |
mcp__* |
eventbus:mcp_call |
→ Agent Service (Store) |
Operator/Engine/Store ──eventbus:agent_continue──► Agent Service
Labels: {
"agent_session_id": "<session-uuid>",
"turn_id": "<turn-number>",
"tool_call_id": "<call-index>",
"status": "success" | "failure",
"reason": "<error message>"
}
Payload: {
"data": {
"output": "<tool result>"
}
}
Workflow/UI ──eventbus:agent_poll──► Agent Service
(agent_svc.go:handleAgentPoll)
Labels: {
"agent_session_id": "<session-uuid>",
"resume_key": "<uuid>",
"timeout": "9s"
}
Response:
{
"channel": "eventbus",
"subject": "agent_response",
"labels": {
"status": "success",
"last_poll": "5"
},
"payload": {
"full_messages": [
{ "content": "...", "is_thinking": "false", "thoughts": "" }
],
"live_message": {
"content": "partial streaming content..."
},
"state": {
"history_len": 6,
"total_tokens": 1500,
"convo_id": "<convo-uuid>"
}
}
}
Labels are used extensively for routing, tracking, and context propagation.
| Label | Used By | Description |
|---|---|---|
sessionID |
Engine | Workflow session identifier |
agent_session_id |
Agent Service | Agent session identifier |
resume_key |
Agent Service | Key for workflow/UI callback |
turn_id |
Agent Service | Current turn number within a session |
tool_call_id |
Agent Service | Index of the tool call being processed |
unified_convo_id |
Agent Service | Cross-conversation identifier |
agent_name |
Agent Service | Name of the invoked agent |
sub_agent_name |
Agent Service | Name of the sub-agent being called |
convo_id |
Agent Service | Conversation identifier |
status |
Universal | success, failure, or error |
reason |
Universal | Error description when status is not success |
feature |
Operator | Driver feature identifier (e.g., driver:kubernetes) |
method |
Operator | Driver method name |
user |
API/Agent | Authenticated user name |
user_provider |
API/Agent | User’s authentication provider |
error |
API | Error message from a responder |
| Full Address | Constant | Direction | Description |
|---|---|---|---|
eventbus:message |
dipper.ChannelEventbus + ":message" |
→ Engine | Incoming driver event |
eventbus:command |
dipper.ChannelEventbus + ":command" |
→ Operator | Function execution |
eventbus:agent_command |
dipper.ChannelEventbus + ":agent_command" |
→ Operator | Agent tool execution |
eventbus:return |
dipper.ChannelEventbus + ":return" |
→ Engine | Function result |
eventbus:return/interrupted |
dipper.ChannelEventbus + ":return/interrupted" |
→ Operator | Interrupted function |
eventbus:agent_continue |
dipper.ChannelEventbus + ":agent_continue" |
→ Engine | Agent tool result |
eventbus:agent_workflow |
dipper.ChannelEventbus + ":agent_workflow" |
→ Engine | Agent workflow trigger |
eventbus:agent_response |
dipper.ChannelEventbus + ":agent_response" |
→ Engine/UI | Agent streaming response |
eventbus:agent_call |
dipper.ChannelEventbus + ":agent_call" |
→ Store | Sub-agent invocation |
eventbus:mcp_call |
dipper.ChannelEventbus + ":mcp_call" |
→ Store | MCP tool call |
agentbus:receive |
"agentbus:receive" |
AI Driver → Agent | Model inference result |
agentbus:rpc/interrupted |
"agentbus:rpc/interrupted" |
AI Driver → Agent | RPC interruption |
broadcast:reload |
"broadcast:reload" |
→ All | Config reload |
scheduler:session |
"scheduler:session" |
→ Engine | Scheduled tick |
api-broadcast |
"api-broadcast" |
→ All | API request |
api:candidate |
"api:candidate" |
Internal | API lock contention |
eventbus:api |
"eventbus:api" |
→ API | API message |