Coordination & Governance

Multi-Agent Event Bus

Give concurrent coding agents live situational awareness across IDEs, terminals, and repositories. Detect file collisions before merge conflicts happen, surface shared focus areas, and broadcast milestones in real time.

<sulcus-peers> Channelterritory.conflictintent.overlapSSE Replay Stream
01 · Situational Awareness

How the Agent Bus Works

When engineers or autonomous agents work in parallel across VS Code, RubyMine, Junie, Claude Code, or Antigravity, Sulcus maintains a tenant-isolated presence table and a 1,000-event ring buffer.
Control Panel · Comms Bus (Live SSE + Peer Presence)
Sulcus Comms Bus showing live peer sessions across RubyMine, VS Code, and Claude Code with a territory file collision banner
The Comms Bus tab tracks active sessions across harnesses, highlights concurrent file collisions in red, manages per-session namespace subscriptions, and streams live coordination events.
120s / 900s
Liveness Windows

Sessions with a heartbeat within 120s report "live", 121s to 900s report "idle", and beyond 15 minutes transition to "offline".

25 Files
Active Territory Cap

Each session tracks up to 25 normalized repo-relative file paths in LIFO order; setting status="offline" clears held territory.

25 Namespaces
Subscription Fan-In

Any session can subscribe to up to 25 ACL-readable namespaces to receive cross-repo broadcasts and peer updates.

1,000 / 24h
Event Ring Buffer

Background pruning runs every 5 minutes, retaining the newest 1,000 events per tenant within a 24-hour rolling window.

02 · Proactive Hazard Detection

Territory Conflicts & Intent Overlaps

Sulcus doesn't wait for agents to poll manually. Every heartbeat and turn ingestion automatically evaluates file territories and declared task intents against active peers.
territory.conflict

Concurrent File Collision Detection

Sulcus normalizes touched paths by stripping workspace_root or anchoring at standard repository roots (crates/, src/, packages/, apps/, plugins/, services/, lib/, tests/). Whenever two non-offline sessions hold the same normalized file path, Sulcus emits a territory.conflict bus event and evaluates on_conflict reactive triggers.

intent.overlap

Semantic Task Focus Overlap

Even when two agents edit different files (for example a React checkout form and a Rails webhook controller), Sulcus tokenizes each session's current_intent into domain terms (≥ 4 chars, stopword-filtered). When two sessions share at least 2 domain tokens (or 1 token with Jaccard similarity ≥ 0.25), Sulcus emits intent.overlap and fires on_intent_overlap triggers (deduplicated per 5-minute window).

Two-Channel Context Injection (<sulcus-peers>)

Peer telemetry never pollutes long-term memory vectors. Instead, harness lifecycle hooks inject a compact <sulcus-peers> block alongside <sulcus-memories>, and Remote MCP responses automatically piggyback unseen bus alerts on tools/call responses (up to 15 unseen events per snapshot):

xmlInjected Peer Coordination Channel
<sulcus-peers>
- [CONFLICT] `services/billing/webhook_verifier.rb` active in [payments-rails, security-playbooks]
- [OVERLAP] [payments-rails, checkout-web] share focus on: [webhook, signature, idempotency]
- [PEER] junie-rm-01 (rubymine, ns=payments-rails, 12s): "Hardening Stripe HMAC timestamp tolerance" | files: services/billing/webhook_verifier.rb
- [milestone.reached] (payments-rails/shared-platform) Published X-Idempotency-Key v2 header contract [files: proto/payments/v2/settlement.proto]
</sulcus-peers>
03 · Bus Operations

Heartbeats, Broadcasts & SSE Streaming

All Agent Bus endpoints are mounted at /api/v1/agent/bus/* (with /api/agent/bus/* supported as a compatibility alias).
bash1. Declare Presence & File Territory
curl -X POST https://api.sulcus.ca/api/v1/agent/bus/heartbeat \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "junie-rm-01",
    "harness": "rubymine",
    "namespace": "payments-rails",
    "subscribed_namespaces": ["payments-rails", "checkout-web", "shared-platform"],
    "git_branch": "feat/stripe-v2-webhooks",
    "status": "working",
    "current_intent": "Hardening Stripe HMAC timestamp tolerance and RSpec replay suite",
    "files_touched": [
      "services/billing/webhook_verifier.rb",
      "spec/services/webhook_verifier_spec.rb"
    ]
  }'
bash2. Fan-Out Cross-Namespace Broadcast
curl -X POST https://api.sulcus.ca/api/v1/agent/bus/broadcast \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "milestone.reached",
    "namespace": "payments-rails",
    "target_namespace": "checkout-web,shared-platform",
    "summary": "Published X-Idempotency-Key v2 header contract for checkout clients",
    "files_touched": ["proto/payments/v2/settlement.proto"]
  }'
bash3. Real-Time SSE Stream with Replay Cursor
# Subscribe to live Server-Sent Events with cursor replay
curl -N https://api.sulcus.ca/api/v1/agent/bus/stream \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Last-Event-ID: 1405"

# Stream output:
# event: bus.connected
# data: {"status":"connected","agent_label":"checkout-web","since_id":1405}
#
# id: 1407
# event: milestone.reached
# data: {"id":1407,"agent_label":"payments-rails","namespace":"shared-platform","event_type":"milestone.reached","summary":"Published X-Idempotency-Key v2 header contract for checkout clients",...}
Broadcast Event Normalization & Trigger Routing
POST /api/v1/agent/bus/broadcast normalizes shorthand event names automatically (milestone or on_milestone becomes milestone.reached; solution becomes solution.discovered; conflict becomes territory.conflict) and fans out across comma-separated target_namespace lists or "all" writable namespaces. Direct bus broadcasts write straight to the event ring buffer and SSE subscribers without re-running the trigger engine, preventing infinite broadcast loops. To evaluate on_milestone or on_solution reactive triggers explicitly, call POST /api/v1/triggers/evaluate or ingest via POST /api/v1/agent/ingest.
04 · Protocol Reference

Agent Bus Endpoints & MCP Tools

GET/api/v1/agent/bus/status
Snapshot active peers, territory_conflicts, intent_overlaps, and recent_events (?namespace, ?since_id, ?limit).
POST/api/v1/agent/bus/heartbeat
Upsert session status (working | idle | compacting | offline), current_intent, and files_touched.
POST/api/v1/agent/bus/broadcast
Publish an event to source namespace, comma-separated target_namespace list, or "all".
GET/api/v1/agent/bus/stream
SSE stream replaying missed events via Last-Event-ID or ?since_id (up to 200 rows) plus live frames.
GET/api/v1/agent/bus/subscriptions
List subscribed namespaces and discover all ACL-readable peer namespaces.
POST/api/v1/agent/bus/subscriptions
Mutate session subscriptions (action: subscribe | unsubscribe | set | list; masks unauthorized targets as 404).
MCPagent_bus_status
Inspect active peer sessions, collisions, overlaps, and recent events directly from an MCP client.
MCPmanage_namespace_connections
List, subscribe, or disconnect cross-namespace bus feeds for the current session.
Namespaces & Two-Gate ACLReactive Triggers