Skip to main content
@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.
deliver must not claim or complete the task. The engine owns the board lifecycle: it creates the task, claims it, opens the execution row and then calls deliver, and it marks the task done itself. A deliver that claimed again would lose to its own claim, and one that completed the task would complete it twice.

The rules it enforces

  • Typed signals only. extractSignals reads a sessions_send or delegate tool call (including TeamChat’s team_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 through deliver’s onQueuedFailure option.
  • A refused delivery says why. When deliver rejects, 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 a DeliveryRefusedError, 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 by caps.maxFanout, counted across the turn’s events. A plan is capped at MAX_PLAN_STEPS and refused whole past it. A lost claim is never retried. After MAX_DELEGATION_FAILURES failures 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 (delegationFailure on EngineBoardClient), 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’s runId repeats 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 (findHandOffCycle from @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 (classifyError from @clawboo/obs, on the error’s code and message), and the class goes on the run’s ledger row. For Auth or Billing the 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. sweepStaleSessions fails a delegated run that sends no event for DELEGATION_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_MS and delivered to the delegator as one [Task Update] (buildTaskUpdateMessage), which also names work still outstanding.
  • A Stop holds work for the next run. holdWorkForNextRun is 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 run writes the run, its stamp and the hand-over of the wakes waiting on the task in one write, and the engine delivers a wake origin naming them. A run that ends well settles them as delivered. With taskWakes, 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’s system origin lists the ids it carries in reportUpIds, and the host copies them onto the run’s RunStamp. When that run ends with done: success the engine settles them as delivered. Any other ending, onSessionClosed, or onRunNotStarted (a queued delivery whose start failed) puts them back to pending. Delivery that runs out of retries gives them up. resume() and every sweepStaleSessions queue 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 after reset() 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 again MAX_REPORT_UP_REPLAYS times is given up instead, with an alert narration to its recipient, and only once that narration is written: narrate returns 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 calls begin(taskId, agentId) before it delivers a fresh run of a task (a fix round is not one), and prepare when the run ends with done: success. prepare returns 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 answers pass (the task is completed as usual), retry with a fix note (the first execution closes as succeeded and a new one delivers the note plus the task’s brief; while isSessionOccupied reports 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 outcome check_failed) or decided (a person moved the card). A check a person’s move overtook finishes nothing, even when the task is running again. A prepare that rejects, a check that throws, or one that has not answered after WORK_CHECK_TIMEOUT_MS of awake time, blocks the task as check_failed too, and so does a done the board refuses while the task is still in_progress or in_review (as done_refused when the check had passed). A check that cannot run whose move to blocked the board refuses stays under check, short of done, 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 written done: if neither the host’s move to blocked nor the engine’s lands, its run is left open for resume() or the board’s stale sweep. markStopped leaves a check under way alone. checksInFlight() counts checks under way, for a host that unloads idle engines. resume() hands a task left in_review with 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 to blocked lands, so a failed move is tried again by the next resume().
  • A person’s move is final. personMovedTask stops 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. markStopped makes a Stop durable at once, so the ready-pump never re-fires stopped work.
  • A person can ask again. dispatchTask runs one todo task 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 is agent:<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 a TurnOrigin, 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.
  • shouldDropAssistantTurn keeps 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.
Last modified on November 7, 2026