​
Transport

Communication between the coordinator and agent processes uses Unix domain sockets with length-prefixed JSON messages. Socket path: instances/{agent_id}/ipc.sock

​
Message Framing

[4 bytes: message length (little-endian u32)] [JSON payload]

​
Coordinator → Agent Messages

​
init

Sent once after the agent process starts: 
{
  "type": "init",
  "agent_id": "agent_abc123",
  "agent_type": "claude-agent",
  "workspace": "/instances/agent_abc123/chronicle/mount",
  "config": {
    "model": "claude-sonnet-4-20250514",
    "ensemble_url": "http://ensemble:8080",
    "ensemble_api_key": "ens_..."
  },
  "state": { ... }  // Hydrated DeltaState (null if stateless)
}

​
message

Deliver a user message for processing: 
{
  "type": "message",
  "id": "msg_123",
  "data": {
    "text": "Fix the failing test",
    "role": "user",
    "attachments": []
  },
  "origin": {
    "tenant_id": "tenant_abc",
    "role": "admin",
    "channel": "web"
  }
}

​
steer

Mid-turn guidance (while agent is processing): 
{
  "type": "steer",
  "content": "Focus on the error handling, not the UI"
}

​
config_update

Runtime configuration change: 
{
  "type": "config_update",
  "changes": {
    "model": "claude-opus-4-20250514",
    "temperature": 0.3
  },
  "source": "user"
}

​
shutdown

Graceful shutdown signal: 
{
  "type": "shutdown",
  "reason": "idle_timeout"
}

​
Agent → Coordinator Messages

​
stream_update

Streaming content update (the primary output mechanism): 
{
  "type": "stream_update",
  "message_id": "msg_out_456",
  "element": {
    "type": "text_delta",
    "text": "Here is the fix..."
  }
}
Element types: text_delta, text_final, tool_call, tool_result, thinking, code_block, file_change, terminal_output

​
state_delta

State mutation (JSON Patch format): 
{
  "type": "state_delta",
  "deltas": [
    {"op": "replace", "path": "/count", "value": 5},
    {"op": "add", "path": "/history/-", "value": "processed message"}
  ]
}

​
log

Structured log entry: 
{
  "type": "log",
  "level": "info",
  "message": "Starting code analysis",
  "module": "agent.analyzer",
  "timestamp": "2025-01-15T10:30:00Z"
}

​
complete

Message processing complete: 
{
  "type": "complete",
  "message_id": "msg_out_456",
  "finish_reason": "end_turn",
  "token_usage": {
    "input_tokens": 1250,
    "output_tokens": 3400,
    "cost": "0.055"
  }
}