Signal contract for agent vendors
This page is for the vendor of a coding agent. It tells you how your agent reports its state to Fleet. Fleet then shows the state in thurbox, proves prompt delivery, and resumes the agent on its conversation.
Your agent needs no Fleet library. It runs one command from its hooks.
Fleet starts your agent your agent's hook
─────────────────────── ─────────────────
env FLEET_SIGNAL_FILE=<file> ───▶ FLEET_SIGNAL_FILE set?
env FLEET_HARNESS=<harness> │ no ──▶ do nothing
│ yes
▼
fleet signal <state> ◀── hook JSON on stdin
│
▼
one JSON line in <file> ──▶ Fleet reads it
The rule #
- Read
FLEET_SIGNAL_FILEfrom the environment. - If it is unset or empty, do nothing. Fleet did not start this session.
- If it is set, run
fleet signal <state>. Write the hook's JSON payload to its standard input. - Ignore the result. Do not fail the agent's turn when
fleetis missing or fails. For example, in a POSIX shell:fleet signal idle 2>/dev/null || true.
fleet signal also does nothing when FLEET_SIGNAL_FILE is unset. The check
in step 2 only saves one process.
Each line fleet signal appends carries seq, the file's length before
the line, plus one. seq is never 0, which stands for no report. The file
only grows, so seq orders the reports, whatever the host's clock says.
Fleet uses that order, not the line's time, to tell whether the agent
reported another prompt after a send. Write lines only through
fleet signal, so that each one has its place.
States #
| State | Run it when | Fleet shows |
|---|---|---|
prompt |
The agent receives a prompt, before the turn starts. | working |
working |
The agent works on a turn, for example before a tool runs. | working |
blocked |
The agent waits for a person to approve something. | attention |
idle |
The turn ends and the agent waits for input. Also at session start. | idle |
Use these rules:
- Send
idleat session start. Fleet then knows the agent is ready for its brief. An agent that sends nothing before its first prompt waits for a person to type it, unless its harness profile knows its ready screen (harness profiles). - Send
blockedonly when a person must act. Do not send it when the agent only waits for its next prompt. - Until the agent sends a state, Fleet shows
unknown. Fleet never guessesidle.
Payload #
The payload is the hook's JSON object. Fleet reads two kinds of field from
it. Each harness profile names the fields in its [payload] table
(harness profiles).
| Field kind | Default names | Value | Fleet uses it to |
|---|---|---|---|
| prompt | prompt, input-messages |
a string, or a list of strings or of parts with a text string |
prove that a prompt reached the agent |
| conversation | session_id, thread-id |
a string | resume the agent on its conversation |
- Fleet stores a prompt only as a digest. It never stores the prompt text.
- A profile can name a paste tag in
[payload] paste. A prompt that is all one<tag …>…</tag …>wrapper then gives two digests: one of the prompt, and one of the text inside the wrapper. A tag inside the text stays part of the text. - A prompt that holds the paste tag anywhere also gives a loose digest: the digest of the prompt without those tags and without whitespace. It proves a text that the agent split around a paste.
- Fleet reads the first conversation field that is a string. An empty string is no conversation.
- Nonempty
background_tasksorsession_cronslists turnidleintoworking: the turn left work running. notification_type = "idle_prompt"turnsblockedintoidle: the agent only waits for its next prompt.- These two state rules apply to every harness. Fleet ignores every other field.
- A payload that is not JSON gives no prompt and no conversation. The state still counts.
fleet signal also takes the payload as its last argument, in place of
stdin.
Which fields Fleet reads #
Fleet sets FLEET_HARNESS to the session's harness name at spawn, and
FLEET_HARNESS_DIR to the directory it read the user's profiles from.
fleet signal reads the payload with the [payload] fields of that
harness's profile:
fleet signal --harness <name>names the harness. It overridesFLEET_HARNESS.- Else
FLEET_HARNESSnames the harness. - A harness with no profile, or no name, uses the default names.
fleet signal reads the user's profiles from FLEET_HARNESS_DIR. Without
it, it reads them beside the config file that this fleet finds
(--config, else FLEET_CONFIG, else the per-user config). A user profile
that fleet signal cannot read does not fail the hook. Fleet skips that one
file, and the bundled profile or the default names apply.
Limits #
- One
fleet signalrun writes one line of at most 4 KiB. - For a session on another place,
FLEET_SIGNAL_FILEis~/.local/state/fleet/signals/<key>.jsonl. Thefleeton that place expands~to its home and makes the directory. Fleet reads the file through the runtime'sexec. A place withoutfleeton itsPATHreports nothing, and the state stays Unknown. - Fleet also passes
FLEET_EVENT_FILE, the session's event outbox: the signal file's name with.eventsafter it.fleet event publishappends to it. A hook never writes to it. See Board.
Examples #
Fleet's own hook files follow this contract (harness profiles).
A hook that reports the end of a turn, with the conversation s1:
[ -n "$FLEET_SIGNAL_FILE" ] || exit 0
printf '%s' '{"session_id":"s1"}' | fleet signal idle 2>/dev/null || true