SwarmForge Handoff Protocol Message Types: A Complete Reference

The SwarmForge handoff protocol defines eight core message types—handshake, task, task-ack, result, error, ready, shutdown, and optional heartbeat—that enable JSON-based communication between the SwarmForge daemon and worker agents.

The SwarmForge handoff protocol is a lightweight, language-agnostic messaging specification used to coordinate work between the central daemon and distributed worker processes. According to the unclebob/swarm-forge source code, this protocol is deliberately minimal to ensure reliable inter-process communication over Unix domain sockets or standard I/O streams. All messages share a common JSON structure with a required type field and payload-specific additional fields.

Core Message Types in the SwarmForge Handoff Protocol

The protocol specification in swarmforge/handoff-protocol.md defines a fixed taxonomy of message types. Each type serves a distinct purpose in the task lifecycle, from connection establishment through result delivery.

handshake: Connection Negotiation

The handshake message initiates communication between the SwarmForge daemon and a worker. It negotiates protocol version and capability exchange.

{
  "type": "handshake",
  "protocol_version": "1.0",
  "supported_message_types": [
    "handshake",
    "task",
    "task-ack",
    "result",
    "error",
    "ready",
    "shutdown"
  ]
}

Direction: Daemon → Worker (initial connection)

task: Work Unit Distribution

The task message carries the complete description of a work unit, including prompt, script, or batch configuration.

{
  "type": "task",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "payload": {
    "prompt": "Write a short essay on the benefits of test-driven development.",
    "language": "en"
  }
}

Direction: Daemon → Worker

task-ack: Receipt Confirmation

The task-ack message acknowledges task receipt and signals worker readiness to begin execution.

{
  "type": "task-ack",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "status": "accepted"
}

Direction: Worker → Daemon

result: Outcome Delivery

The result message returns completed task output, execution status, and any generated data.

{
  "type": "result",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "output": "Test-driven development (TDD) encourages ...",
  "exit_code": 0
}

Direction: Worker → Daemon

error: Failure Reporting

The error message communicates task processing failures with diagnostic context.

{
  "type": "error",
  "task_id": "c7f8a9e2-3d1b-4f6e-9a2b-0d5e7c1f9b34",
  "message": "Unable to spawn subprocess: file not found",
  "code": 101
}

Direction: Worker → Daemon

ready: Worker Availability Signal

The ready message announces idle status and capacity to accept new tasks.

{
  "type": "ready",
  "worker_id": "worker-42"
}

Direction: Worker → Daemon

shutdown: Graceful Termination

The shutdown message requests orderly connection closure from either party.

{
  "type": "shutdown",
  "reason": "normal termination"
}

Direction: Bidirectional (Daemon ↔ Worker)

heartbeat: Connection Maintenance (Optional)

The heartbeat message keeps connections alive and enables health monitoring.

{
  "type": "heartbeat",
  "timestamp": 1723589123
}

Direction: Bidirectional (Daemon ↔ Worker)

Implementation Files and Test Coverage

The SwarmForge handoff protocol is implemented across several source files with comprehensive test coverage:

• swarmforge/handoff-protocol.md — Formal specification documenting all SwarmForge handoff protocol message types and their schemas
• swarmforge/scripts/handoff_lib.bb — Babashka implementation of protocol serialization, deserialization, and helper functions used by daemon scripts
• test/swarmforge/script_test.clj — Integration test suite validating end-to-end message handling workflows
• test/swarmforge/handoff_test.clj — Unit tests focused specifically on protocol compliance and edge case handling

Summary

• The SwarmForge handoff protocol uses eight core message types: handshake, task, task-ack, result, error, ready, shutdown, and optional heartbeat
• All messages are JSON-encoded with a mandatory type field and payload-specific additional fields
• The protocol supports bidirectional communication between daemon and workers over Unix domain sockets or standard I/O
• Complete specification lives in swarmforge/handoff-protocol.md with reference implementation in handoff_lib.bb

Frequently Asked Questions

What is the minimum required field for every SwarmForge handoff protocol message?

Every message must include a type field containing one of the defined message type strings. The protocol rejects any JSON object lacking this field. Additional required fields vary by message type—for example, task messages require task_id and payload, while result messages require task_id and output.

How does the SwarmForge daemon discover worker capabilities?

Capability discovery occurs during the handshake exchange. The daemon sends its supported_message_types array, and the worker responds with its own capabilities. Both parties must agree on protocol version (currently "1.0") before task distribution begins. This negotiation prevents version mismatch errors during active work distribution.

Can workers send tasks to other workers using this protocol?

No. The SwarmForge handoff protocol defines an asymmetric communication pattern where only the daemon originates task messages. Workers operate in a request-response model: they signal ready state, receive task assignments, and return result or error responses. Peer-to-peer task delegation is not supported by the current protocol specification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}