Work: from a request to a result
A person asks their lead agent (the chief of staff). The lead agent starts an orchestrator. The orchestrator starts workers. Results come back up. Solid arrows are pushed. Dashed loops are polled.
Code: fleet/internal/api/spawn.go, fleet/internal/node/agent.go (claim),
fleet/internal/api/reports.go, fleet/internal/supervisor/supervisor.go,
fleet/internal/sched/sched.go.
What is pushed, and what is polled
| From, to | How | Code |
|---|---|---|
| Server to node: a new turn | Polled. The node claims every 10 s and when a turn ends. | fleet/internal/node/agent.go |
Anyone to an idle agent: fleet send |
Pushed. The message wakes the scheduler, which starts a turn. | fleet/internal/mailbox/mailbox.go, fleet/internal/sched/sched.go |
Worker to its parent agent: fleet done |
Not sent. The parent must poll. | fleet/internal/supervisor/supervisor.go |
Worker to its parent agent: a turn that ends with no done |
Pushed. The parent gets "NAME is waiting: REASON" in its inbox. | noteParent in supervisor.go |
| Agent to the person or the lead agent | Not sent. The lead agent polls. Only a question (ask) goes to Telegram. |
ask-telegram.md |
| Server to the page | Polled. The page reads /api/state every 15 s. |
fleet/internal/web/index.html |
The gap
A lead agent that is not a fleet agent has no inbox. It learns of a result only when it polls. An agent with no parent gets no note at all: the person reads its state on the page. Between two polls, a worker that hangs and does not change state is not seen. Issue #230 is the design for how to watch workers. It is open and not built.
When a worker ends a turn without done
fleet doneis refused (409) while unread messages wait for the agent.fleet status --blockedmakes the stateblockedat the end of the turn. It does not send a message to anyone.- No turn has a default time limit and nothing stops a silent turn. A node flags one as
silent(fleet/internal/node/hang.go). A limit exists only with--time-cap-s.
More sequences
- A crash and its retries, and a server restart.
- A stuck turn: retry, then a stronger model, then blocked.
- A node lost for 15 minutes, and its agent made again on another node.
- A profile paused at its usage limit, and the resume at the reset time.
- A member removed: tokens revoked, agents stopped, nodes get no more turns.
- A secret to one turn, also in a kubejob pod.
- A backup, and a restore on a new box.
Not drawn yet: a profile paused for a bad login with fleet profile rotate, and a message from
another project member with wake: project.