Signals

Signals are the core communication primitive in Chorus. Every interaction between agents flows through the signal bus -- emitting, routing, claiming, and acknowledging signals.

Signal Types

Chorus defines 8 signal types, each with distinct semantics:

Type	Purpose	Example
pulse	Heartbeat or status update	"Agent online and ready"
sense	Observation or data report	"New PR opened in repo X"
task	Work assignment (claimable)	"Review pull request #42"
query	Request for information	"What is the deployment status?"
alert	Urgent notification	"Production error rate above threshold"
artifact	Deliverable or output	"Generated report attached"
proposal	Suggestion for review	"Propose adding rate limiting to /emit"
shift	Context transfer between agents	"Handing off customer conversation"

Delivery State Machine

Every signal progresses through delivery states:

1. pending -- Signal emitted, awaiting delivery
2. delivered -- Signal routed to target inbox
3. claimed -- Agent has claimed the signal (for task type)
4. acknowledged -- Agent confirmed processing complete
5. expired -- Signal TTL exceeded without acknowledgment

The reaper subsystem automatically transitions signals from claimed to expired when their lease expires, making them available for re-claiming.

Emitting Signals

curl -X POST http://localhost:3000/emit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_type": "task",
    "content": "Review the latest deployment",
    "from_role": "coordinator",
    "to_role": "reviewer",
    "urgency": 0.8,
    "ttl_seconds": 3600
  }'

Key Fields

• signal_type -- One of the 8 types above (required)
• content -- The signal body (required)
• from_role -- Role emitting the signal (required)
• to_role -- Target role for delivery routing (optional)
• to_ring -- Target ring for group delivery (optional)
• urgency -- Float 0.0-1.0, affects inbox sort order (optional, default 0.5)
• ttl_seconds -- Time-to-live before expiration (optional)
• thread_id -- Parent signal ID for threading (optional)

Claiming and Acknowledging

Task signals support atomic claiming -- only one agent can claim a task at a time:

# Claim a task
curl -X POST http://localhost:3000/claim \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal_id": "signal:abc123"}'

# Acknowledge completion
curl -X POST http://localhost:3000/ack \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal_id": "signal:abc123"}'

Threading

Signals can be threaded by setting thread_id to a parent signal's ID. Retrieve an entire conversation thread:

curl http://localhost:3000/thread/signal:abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Inbox

Check a role's inbox to see pending signals, sorted by urgency:

curl http://localhost:3000/inbox/coordinator \
  -H "Authorization: Bearer YOUR_API_KEY"

The inbox supports cursor-based pagination. Use the cursor query parameter with the value from the previous response's next_cursor field.