Reference: agent states and events

Agent states

State	Shown as	Meaning
`stopped`	arrêté	No process. The initial state of every agent.
`starting`	démarre…	The process is launched and the ACP handshake (`initialize`) is in progress.
`ready`	prêt	Running and idle.
`busy`	occupé	Running and used by at least one conversation.
`error`	erreur	The start failed, or the process exited on its own (crash). The status carries the reason, followed by the agent's last stderr lines for a failed start.

outdated (shown as « à redémarrer ») is set on a running agent whose definition changed in the configuration; a restart applies it.

Transitions

From	Event	To
`stopped`, `error`	start requested (▶ in the Agents panel, or first use)	`starting`
`starting`	handshake succeeds	`ready`
`starting`	handshake fails, protocol other than ACP v1, timeout (30 s)	`error`
`ready`	used	`busy`
`busy`	last user done	`ready`
`ready`, `busy`	stop requested (■), application quits, agent removed from the configuration	`stopped`
`ready`	unused for `limits.stopIdleAgentsAfter` (checked every 30 s)	`stopped`
`ready`	another agent must start and this one is the least recently used idle agent	`stopped`
`ready`, `busy`	the process exits on its own	`error` (never restarted automatically)
`starting`	stop requested	`stopped` once the start ends

When limits.maxRunningAgents agents are running and all are busy, a start is refused with the message too many agents running: N agent(s) busy (…), the limit is N.

Stopping an agent closes its stdin, waits 5 seconds, then kills its process group (the agent and what it started, such as mm under scripts/agents.sh).

Events from Go to the interface

Event	Payload	Sent when
`config:changed`	`{path, valid, problems[]}`	The configuration file was saved and reloaded (valid or not).
`agent:state`	`{agent, state, error?}`	An agent changes state or its definition changes.
`agent:log`	`{agent, line}`	An agent writes a line on its standard error.

The Go names and types are in internal/events; the TypeScript constants and types are generated in frontend/bindings/events and frontend/bindings/…/internal/events.

Services called by the interface

Service	Method	Effect
`AgentService`	`List()`	Every agent with `name, title, icon, description, state, error, outdated`, in configuration order.
	`Start(name)`, `Stop(name)`, `Restart(name)`	As in the transitions above; an error is returned to the interface.
	`Logs(name)`	The last 200 stderr lines of the agent.
`ConfigService`	`Current()`	`path, source, created, valid, problems[], warnings[], theme, language, channels[]`.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


# Reference: agent states and events

## Agent states

| State | Shown as | Meaning |
| --- | --- | --- |
| `stopped` | arrêté | No process. The initial state of every agent. |
| `starting` | démarre… | The process is launched and the ACP handshake (`initialize`) is in progress. |
| `ready` | prêt | Running and idle. |
| `busy` | occupé | Running and used by at least one conversation. |
| `error` | erreur | The start failed, or the process exited on its own (crash). The status carries the reason, followed by the agent's last stderr lines for a failed start. |

`outdated` (shown as « à redémarrer ») is set on a running agent whose definition changed in the configuration; a restart applies it.

## Transitions

| From | Event | To |
| --- | --- | --- |
| `stopped`, `error` | start requested (▶ in the Agents panel, or first use) | `starting` |
| `starting` | handshake succeeds | `ready` |
| `starting` | handshake fails, protocol other than ACP v1, timeout (30 s) | `error` |
| `ready` | used | `busy` |
| `busy` | last user done | `ready` |
| `ready`, `busy` | stop requested (■), application quits, agent removed from the configuration | `stopped` |
| `ready` | unused for `limits.stopIdleAgentsAfter` (checked every 30 s) | `stopped` |
| `ready` | another agent must start and this one is the least recently used idle agent | `stopped` |
| `ready`, `busy` | the process exits on its own | `error` (never restarted automatically) |
| `starting` | stop requested | `stopped` once the start ends |

When `limits.maxRunningAgents` agents are running and all are `busy`, a start is refused with the message `too many agents running: N agent(s) busy (…), the limit is N`.

Stopping an agent closes its stdin, waits 5 seconds, then kills its process group (the agent and what it started, such as `mm` under `scripts/agents.sh`).

## Events from Go to the interface

| Event | Payload | Sent when |
| --- | --- | --- |
| `config:changed` | `{path, valid, problems[]}` | The configuration file was saved and reloaded (valid or not). |
| `agent:state` | `{agent, state, error?}` | An agent changes state or its definition changes. |
| `agent:log` | `{agent, line}` | An agent writes a line on its standard error. |

The Go names and types are in `internal/events`; the TypeScript constants and types are generated in `frontend/bindings/events` and `frontend/bindings/…/internal/events`.

## Services called by the interface

| Service | Method | Effect |
| --- | --- | --- |
| `AgentService` | `List()` | Every agent with `name, title, icon, description, state, error, outdated`, in configuration order. |
| | `Start(name)`, `Stop(name)`, `Restart(name)` | As in the transitions above; an error is returned to the interface. |
| | `Logs(name)` | The last 200 stderr lines of the agent. |
| `ConfigService` | `Current()` | `path, source, created, valid, problems[], warnings[], theme, language, channels[]`. |