IPC Protocol

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://127.0.0.1:8004",
    "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"
  }
}