Docs/Gateway/Fleet messaging
Gateway

Sessions talking to sessions

3 min read

Agents in a DevThrottle fleet can talk to each other: hand work sideways, ask a teammate a question and wait for the answer, or spin up a new session - on this machine or another one. That is what makes missions work: an architect that plans, a manager that supervises, workers that build, all coordinating themselves.

The verbs

From inside any session
cc-devthrottle message send <session> "message"
cc-devthrottle message ask <session> "question"
cc-devthrottle session spawn <repo> --machine <name>
  • send - deliver a one-way message. Target one session by name or a short id, or your whole team with all.
  • ask - ask ONE session a question and wait for its answer (up to two minutes by default).
  • spawn - open a new session, locally or on another machine. A session spawned by another session defaults to a Worker supervised by its spawner.

Every delivered message arrives stamped with who sent it - the session's name, machine, and id - so a receiving agent always knows who is talking, and the stamp cannot be forged by the sender.

Between a session and the one driving it

The three verbs above are how any session reaches any other. Supervision is a narrower relationship and it has two verbs of its own: a spawned session is a Worker, and the session that spawned it is the one driving it.

From inside any session
cc-devthrottle session raise "what you are blocked on"
cc-devthrottle session raise --clear
cc-devthrottle session workers
  • raise - a supervised session puts its hand up to the session driving it. It is quiet toward you by construction, so this is the channel it has instead. Raise it only while you are still working and have hit something you cannot decide inside your mandate: an ambiguous requirement, an irreversible step, a real design fork, an authorisation you do not hold. Not for progress, and not for "I finished" - stopping already says that. A raised hand lowers itself when that session's turn ends, and --clear takes it down once the decision is answered.
  • workers - the other side of it: one line listing the sessions you are driving, what state each is in, and what any of them is blocked on. A manager learns what its workers are doing by reading them, not by being messaged "notice me". With nobody under you it simply says so.

The safety rails

A message interrupts the receiving agent, so messaging is deliberately fenced:

  • Your team by default. send all reaches only your own team - your mission's sessions, or for a solo session, the sessions in the same repository on the same machine.
  • The whole fleet needs a human. A genuine fleet-wide broadcast requires --everyone plus a human-issued grant and a written --reason. Grants expire after ten minutes and are logged. An agent cannot mint its own grant.
  • Rate limits and dedupe. Each sender is throttled (a handful of broadcasts per minute) and duplicate messages are refused - a runaway agent cannot storm the fleet, even inside its own team.
  • Nothing drops silently. An unknown target, an unreachable machine, or a refused broadcast comes back as a clear error to the sender.
Warning
If an agent asks you for a fleet-wide broadcast, treat it like a production action: issue the grant only when interrupting every agent on every machine is genuinely warranted, and say why - the reason is logged.
Note
Under the hood these verbs go through the Gateway, carrying the calling session's own key: the Gateway stamps the sender, resolves the team, and reaches the owning Director down that Director's outbound connection. It is the same surface your own scripts use - see the Control API.