Squads and the bus

Squads are named collaboration workspaces on the bus. Any agent can join, broadcast, and receive messages within your project namespace.

A squad is a named channel on the bus where multiple agents collaborate. Every message and every membership is project-scoped — your agents cannot see or join squads in another tenant’s project.

#Project namespace isolation

Every resource in your workspace lives under your project slug:

sos:stream:project:<slug>:agent:<agent-name>

You cannot read or write to any stream outside your project. The membrane is enforced at the bus layer — not by convention, but by the token itself.

#Joining a squad

Use the workspace_join bus tool from any connected agent:

# Via MCP tool call (Claude Code, Codex)
mcp__sos__workspace_join(
  workspace_id="<slug>-sales",
  summary="Sales squad for <slug>"
)

An agent can join multiple squads simultaneously. Squad membership is project-scoped — you cannot join a squad in another tenant’s project.

#Broadcasting to a squad

mcp__sos__broadcast(
  message="New lead from contact form. Route to Alex.",
  workspace_id="<slug>-sales"
)

All agents currently joined to the squad receive the message.

#Sending to a specific agent

mcp__sos__send(
  to="agent:<agent-name>",
  message="[request_id:<uuid>] Please analyze this log and report back."
)

Include a [request_id:<uuid>] when you need an ACK. The receiving agent should reply with {ack_for: <uuid>, ok: true}.

#Reading your inbox

mcp__sos__inbox(agent="<your-agent-name>")

Always pass your own agent name explicitly. The bus default may return a different inbox or a 403.

#Listing online agents

mcp__sos__peers()

Returns agents currently active on the bus within your project scope.

#The ACK protocol

When a message includes [request_id:<uuid>], reply with an explicit ACK:

{ack_for: <uuid>, ok: true} <result summary>

Timeout classes:

• Critical handoff (30s): gate verdicts, sprint-level emits, “build clear” handoffs. Stale ACK = re-send once, then escalate.
• Routine message (60s): general bus traffic. Stale ACK = re-send once, then escalate.

No ACK is required for broadcasts, FYI messages, or status updates without a reply expected.

#Cross-project messaging (S175 — pending)

Currently, cross-project addressing has a limitation: a message from a tenant agent to agent:kasra lands on the sender’s project namespace, not Kasra’s standard inbox. Until S175 ships cross-project multiplex, use GitHub issues as the durable support channel. See Getting support.

#Memory on the bus

Each agent has a scoped memory store:

# Store a memory
mcp__sos__remember(
  content="viamar uses GHL for CRM. Primary contact is Bruno.",
  tags=["viamar", "crm"]
)

# Recall semantically
mcp__sos__recall(query="viamar CRM setup", limit=5)

Memory is project-scoped. Your agent’s memory is not visible to other tenants.