@clawboo/team-orchestration is the engine behind team chat. It watches each agent’s run events, turns delegation
signals into board tasks, delivers each task to the agent it names, and reports results back to whoever delegated
them. It is pure and browser-safe: the board, delivery, narration and every other side effect arrive as injected
functions, so the same engine runs on the server against SQLite and in tests against an in-memory board.
Use this page when you change how a team delegates, reports back or recovers. The model is on
How work is delegated, and how a message reaches the engine is on
How a team works.
How the server runs it
apps/web/server/lib/teamChat/teamOrchestrator.ts builds one long-lived engine per team chat room: the team’s own
chat is its default room, and each extra room gets its own engine. Each engine is created with
createBoardOrchestrator(deps), wired to the database through serverBoardClient.ts and to the runtimes through
serverDeliver.ts. The SPA uses only the helpers (session keys, the [Task Update] builder, control-token checks)
and talks to the server over REST and server-sent events.
The rules it enforces
- Typed signals only.
extractSignalsreads asessions_sendordelegatetool call (including TeamChat’steam_delegate), or a<delegate to="@Name">or<plan>block in a finished turn. It never infers delegation from prose. The tag parsers tolerate a missing opening<, and stripping removes the whole tag from what the chat shows. - One task per session. A session works one task at a time. A message for a busy session waits in the nudge
queue (
createNudgeQueue) and goes out at its next turn boundary. A queued message whose run never starts frees the session for the next one, and its sender hears of it throughdeliver’sonQueuedFailureoption. - A refused delivery says why. When
deliverrejects, the engine fails the task at once instead of waiting for the watchdog. A host that decided not to start the run, such as the web server when a hard-cap budget is paused, rejects with aDeliveryRefusedError, and its message becomes the task’s failure comment and what the delegator is told. Any other rejection is reported as a message the agent did not receive. - Bounded trees. Delegation depth is capped by
MAX_SPAWN_DEPTH, the same constant the board and the task runner use, and fan-out per turn bycaps.maxFanout, counted across the turn’s events. A plan is capped atMAX_PLAN_STEPSand refused whole past it. A lost claim is never retried. AfterMAX_DELEGATION_FAILURESfailures in a row of the same task by the same agent, the engine refuses to delegate it to that agent again and tells the delegator to handle it another way. The count lives on the board (delegationFailureonEngineBoardClient), so it outlives the engine. - One task, no circles. A hand-off goes through
createHandOff, the capped create: its key from the delivery (RunStamp.deliveryId, since an event’srunIdrepeats across turns on a resumed native session), the target and the words returns the same task on a replay, and an open task with the same words from another turn is returned instead of a second one, with one note to the sender. A hand-off back to an agent that delegated an open task on the sender’s chain is refused (findHandOffCyclefrom@clawboo/board-core), unless the target is the lead. - Account failures are not re-delegated. A run that ends on a fatal error is filed under its class
(
classifyErrorfrom@clawboo/obs, on the error’s code and message), and the class goes on the run’s ledger row. ForAuthorBillingthe task’s comment says the sign-in or the account was refused, the failure report tells the delegator not to re-delegate or retry it and to tell the user. Nothing blocks a re-delegation in code, so once a person has fixed the sign-in they can ask for it again in chat; the loop breaker above still caps repeats. Only the runtime’s own error is classified, never a failed run’s summary, which can be the agent’s prose about anything. - Silence fails a delegation.
sweepStaleSessionsfails a delegated run that sends no event forDELEGATION_IDLE_TIMEOUT_MS, with longer allowances while a tool call is open or a run waits to start, and tells the delegator. The values are on Limits and defaults. - Results are batched. Finished tasks are gathered for
REFLECT_WINDOW_MSand delivered to the delegator as one[Task Update](buildTaskUpdateMessage), which also names work still outstanding. - A Stop holds work for the next run.
holdWorkForNextRunis the one place for the rule: a person’s Stop drops nothing and starts nothing. Every report-up and saved wake the room holds, and a result from a run delivered before the Stop, stays pending and leaves the sweep.takeHeldReportUps(sessionKey)hands the recipient’s next run its held report-ups, whatever started it, as text for its context, and the host adds their ids to the run’s stamp, so they settle like any other when it ends. Nothing a Stop held is counted as a replay. - Saved wakes. A claim made with a
runwrites the run, its stamp and the hand-over of the wakes waiting on the task in one write, and the engine delivers awakeorigin naming them. A run that ends well settles them as delivered. WithtaskWakes, a person’s comment the run did not hear gets a turn before Done (offerCommentTurn), through the same path as a fix round. - Results survive a restart. With
reportUps, each item is recorded when it is queued. The update’ssystemorigin lists the ids it carries inreportUpIds, and the host copies them onto the run’sRunStamp. When that run ends withdone: successthe engine settles them as delivered. Any other ending,onSessionClosed, oronRunNotStarted(a queued delivery whose start failed) puts them back to pending. Delivery that runs out of retries gives them up.resume()and everysweepStaleSessionsqueue each pending item the engine does not hold, so a room’s next engine sends it again and this one never sends it twice. An engine settles only items it still holds, and lets one go only once its settlement is written (the sweep writes a settlement that failed), so afterreset()a run cancelled at teardown leaves its items for the next engine;reset()does not flush them either. An item whose recipient cannot be reached yet (a room with no lead) waits without being counted. An item already sent againMAX_REPORT_UP_REPLAYStimes is given up instead, with analertnarration to its recipient, and only once that narration is written:narratereturns false for an alert that reached nowhere, and the item stays pending until a later sweep’s alert lands. - Work is checked before it is done. With
workCheck, the engine callsbegin(taskId, agentId)before it delivers a fresh run of a task (a fix round is not one), andpreparewhen the run ends withdone: success.preparereturns null when there is nothing to check; otherwise the engine runs the returned check without awaiting it in the run’s drain. Meanwhile the session stays bound to the task: no other task is bound to it, the idle watchdog skips it, and its other turns’ terminals are not the task’s. The check answerspass(the task is completed as usual),retrywith a fix note (the first execution closes as succeeded and a new one delivers the note plus the task’s brief; whileisSessionOccupiedreports another turn the session stays under check and the fix round waits for that turn’s end, and after a Stop none starts; a fix round whose board writes fail before it is sent fails the session with the error, like a rejected delivery, and keeps the task’s later plan steps queued),failed(the host blocked the task; the delegator’s[Task Update]has the outcomecheck_failed) ordecided(a person moved the card). A check a person’s move overtook finishes nothing, even when the task is running again. Apreparethat rejects, a check that throws, or one that has not answered afterWORK_CHECK_TIMEOUT_MSof awake time, blocks the task ascheck_failedtoo, and so does adonethe board refuses while the task is stillin_progressorin_review(asdone_refusedwhen the check had passed). A check that cannot run whose move toblockedthe board refuses stays under check, short ofdone, and the sweep tries the move again until it lands or a person moves the card (a task it cannot read counts as still the check’s). Work that failed its check is never writtendone: if neither the host’s move toblockednor the engine’s lands, its run is left open forresume()or the board’s stale sweep.markStoppedleaves a check under way alone.checksInFlight()counts checks under way, for a host that unloads idle engines.resume()hands a task leftin_reviewwith a running engine execution and no check of its own (a restart or teardown cut it short) to a person and tells its delegator (check_interrupted); it closes that execution only once the move toblockedlands, so a failed move is tried again by the nextresume(). - A person’s move is final.
personMovedTaskstops the run working on the card, closes its execution as cancelled, and tells the delegator when the person marked it done or cancelled it. A run that ends after that changes nothing.markStoppedmakes a Stop durable at once, so the ready-pump never re-fires stopped work. - A person can ask again.
dispatchTaskruns onetodotask now because a person asked, skipping the automatic fire policy. A person-assigned task reports on its card, not to the team’s lead.
Session keys
A team session key isagent:<agentId>:team:<teamId>, with :room:<roomId> appended for a room other than the
team’s own chat. buildTeamSessionKey(agentId, teamId, roomId?) writes one, and parseTeamSessionKey,
agentIdFromSessionKey, teamIdFromSessionKey and roomIdFromSessionKey read one back; isTeamSessionKey is true
with or without a room. A person’s 1:1 chat with a Clawboo Native agent uses nativeChatSessionKey(agentId), which
is agent:<agentId>:native; the web server keys a Claude Code, Codex or Hermes agent’s 1:1 chat
agent:<agentId>:<runtime>. Build and parse keys only through these helpers, so the room suffix stays readable.
Turn origins
Whoever asks for a turn stamps it with aTurnOrigin, passed as deliver’s fourth argument, because the engine’s
own view of a session goes stale as soon as a task completes.
classifyTurn turns an origin into the framing the prompt needs (worker, leader, user-facing), and isChatVisible
answers the last column. Never derive visibility from the framing: a person’s @mention to a busy worker is framed as
a worker turn but still gets an answer in the chat.
Other helpers
buildTurnEnvelope({ ambient, addressed })frames waiting context in two parts: items addressed to this agent, first, and ambient evidence that carries no authority to change the task. Membership comes from where an item came from, never from its text.shouldDropAssistantTurnkeeps control tokens (RESUME_ACK_TOKEN,SKIP_ACK_TOKEN) and short refusals out of the transcript.
Test it
@clawboo/team-orchestration/contract exports runCascadeContract(harness), the shared suite of cascade scenarios:
stop and release, the idle watchdog and its allowances, one task per session, reflect batching, the fan-out cap,
plan steps cancelled after a failed dependency, the loop breakers, claims never retried, the ready-pump’s fire
policy, follow-ups on closed tasks, and work delivered before a Stop. It runs twice: against the package’s
in-memory board (pnpm --filter @clawboo/team-orchestration test), and against the real server board client over
SQLite in apps/web/server/lib/teamChat/__tests__/boardOrchestration.contract.test.ts, so the fake and the real
board cannot drift apart. Add a scenario to src/contract.ts when you add a rule.
Related
- How work is delegated: how a team delegates and reports back.
- @clawboo/board-core: the task rules the engine dispatches by.
- Board internals: claims, heartbeats and reconciliation underneath the engine.
- Work with your team in chat: rooms, General and the chat a person sees.