Référence : états des agents et événements

  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
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

# Référence : états des agents et événements

## États d'un agent

| État | Affiché (`en` · `fr`) | Signification |
| --- | --- | --- |
| `stopped` | stopped · arrêté | Aucun processus. L'état initial de chaque agent. |
| `starting` | starting… · démarre… | Le processus est lancé et la poignée de main ACP (`initialize`) est en cours. |
| `ready` | ready · prêt | En marche et inoccupé. |
| `busy` | busy · occupé | En marche et utilisé par au moins une conversation. |
| `error` | error · erreur | Le démarrage a échoué, ou le processus s'est arrêté seul (crash). Le statut porte la raison, suivie des dernières lignes stderr de l'agent en cas d'échec au démarrage. |

`outdated` (affiché « restart to apply changes », ou « à redémarrer » en français) marque un agent en marche dont la définition a changé dans la configuration ; un redémarrage l'applique.

## Transitions

| Depuis | Événement | Vers |
| --- | --- | --- |
| `stopped`, `error` | démarrage demandé (▶ dans le panneau Agents, ou première utilisation) | `starting` |
| `starting` | la poignée de main réussit | `ready` |
| `starting` | la poignée de main échoue, protocole autre qu'ACP v1, délai dépassé (30 s) | `error` |
| `ready` | utilisé | `busy` |
| `busy` | le dernier utilisateur a fini | `ready` |
| `ready`, `busy` | arrêt demandé (■), fermeture de l'application, agent retiré de la configuration | `stopped` |
| `ready` | inutilisé depuis `limits.stopIdleAgentsAfter` (vérifié toutes les 30 s) | `stopped` |
| `ready` | un autre agent doit démarrer et celui-ci est l'agent inoccupé utilisé le moins récemment | `stopped` |
| `ready`, `busy` | le processus s'arrête seul | `error` (jamais redémarré automatiquement) |
| `starting` | arrêt demandé | `stopped` dès la fin du démarrage |

Quand `limits.maxRunningAgents` agents tournent et qu'ils sont tous `busy`, un démarrage est refusé avec le message `too many agents running: N agent(s) busy (…), the limit is N`.

Arrêter un agent ferme son entrée standard, attend 5 secondes, puis tue son groupe de processus (l'agent et ce qu'il a lancé, comme `mm` sous `scripts/agents.sh`).

## Événements du Go vers l'interface

| Événement | Charge | Envoyé quand |
| --- | --- | --- |
| `config:changed` | `{path, valid, problems[]}` | Le fichier de configuration a été enregistré et rechargé (valide ou non). |
| `agent:state` | `{agent, state, error?}` | Un agent change d'état ou sa définition change. |
| `agent:log` | `{agent, line}` | Un agent écrit une ligne sur sa sortie d'erreur. |

Les noms et types Go sont dans `internal/events` ; les constantes et types TypeScript sont générés dans `frontend/bindings/events` et `frontend/bindings/…/internal/events`.

## Services appelés par l'interface

| Service | Méthode | Effet |
| --- | --- | --- |
| `AgentService` | `List()` | Tous les agents avec `name, title, icon, description, state, error, outdated`, dans l'ordre de la configuration. |
| | `Start(name)`, `Stop(name)`, `Restart(name)` | Comme dans les transitions ci-dessus ; une erreur est renvoyée à l'interface. |
| | `Logs(name)` | Les 200 dernières lignes stderr de l'agent. |
| `ConfigService` | `Current()` | `path, source, created, valid, problems[], warnings[], theme, language, channels[]`. |

## Conversations (milestone M2)

Une conversation par agent, gardée en mémoire jusqu'à la fermeture de l'application ou l'ouverture d'une autre configuration.

### Messages

| Champ | Signification |
| --- | --- |
| `id`, `agent`, `createdAt` | identité |
| `role` | `user`, `agent` ou `system` |
| `parts` | `text` (Markdown), `thought` (réflexion), `tool` (un tool call), `plan` (étapes du plan) |
| `done` | faux tant qu'un message d'agent arrive |
| `queued` | un message de l'utilisateur qui attend la fin de la réponse en cours |
| `stopReason` | comment s'est terminé un message d'agent : `end_turn`, `cancelled`, `max_tokens`, `max_turn_requests`, `refusal` |
| `error` | pourquoi un message d'agent s'est terminé sans stop reason (l'explication de l'agent lui-même), ou `cancelled` pour un message en attente abandonné par Arrêter |
| `code` | messages système : `agent-restarted` (nouvelle session, l'agent a oublié le début), `agent-unavailable` (impossible de le démarrer ou de le joindre ; `error` dit pourquoi) |

Un tool call a `id, title, kind` (`read, edit, delete, move, search, execute, think, fetch, other`), `status` (`pending, in_progress, completed, failed`), `input` (JSON compact), `output`, `locations`, `diffs` (`path, oldText, newText, newFile`).

### Événements

| Événement | Charge | Envoyé quand |
| --- | --- | --- |
| `message:updated` | `{agent, message}` | un message est ajouté, ou terminé |
| `message:delta` | `{agent, messageId, index, kind, text?, part?}` | `text` s'ajoute à la partie `index` (texte, réflexion), ou `part` la remplace (outil, plan) |
| `turn:changed` | `{agent, busy, queued}` | l'agent commence ou finit de répondre ; `queued` messages attendent |
| `permission:requested` | `{id, agent, messageId, toolCall, options[], rejections}` | l'agent demande à utiliser un outil ; `rejections` compte les refus déjà donnés dans ce tour |
| `permission:resolved` | `{id, agent}` | la demande a reçu une réponse, ou a été annulée par Arrêter |
| `usage:changed` | `{agent, usage: {used, size}}` | l'agent a indiqué l'usage de sa fenêtre de contexte (`size` vaut 0 si inconnue) |

### `ChatService`

| Méthode | Effet |
| --- | --- |
| `Send(agent, text)` | Ajoute un message de l'utilisateur et renvoie son id ; démarre l'agent si besoin ; met le message en attente si l'agent répond. Texte vide et agent inconnu sont des erreurs. |
| `Cancel(agent)` | Arrête la réponse en cours (`session/cancel`), répond « annulé » aux demandes de permission en attente, abandonne les messages en attente. |
| `AnswerPermission(id, optionId)` | Répond à une demande avec l'une de ses options. |
| `Conversation(agent)` | Toute la conversation : `messages, busy, queued, usage, commands, permissions`. |

### Méthodes Settings de `ConfigService`

| Méthode | Effet |
| --- | --- |
| `Content()` | Le texte du fichier de configuration. |
| `Validate(text)` | Les problèmes et avertissements de `text`, avec `line, column, message, warning`, sans enregistrer. |
| `Save(text)` | Écrit `text` s'il est valide ; sinon renvoie ses problèmes et n'écrit rien. |
| `Schema()` | Le JSON Schema de la configuration. |
| `Open(path)` | Arrête tous les agents, oublie les conversations, charge et surveille `path`, le mémorise. |
| `Choose()` | Affiche le sélecteur de fichier natif et ouvre le fichier choisi ; renvoie `""` en cas d'annulation. |
| `Recent()` | Les fichiers de configuration ouverts depuis l'application, du plus récent au plus ancien (8 au plus). |

### Arrêt d'un agent

L'entrée standard de l'agent est fermée ; après 5 s, l'agent et ses enfants reçoivent SIGTERM (le temps pour `scripts/agents.sh` de décharger le modèle) ; 3 s plus tard, SIGKILL.