Workspaces et terminaux — explication

De quoi s'agit-il ?

Un agent travaille dans un dossier : ses instructions (AGENTS.md), ses skills, ce qu'il écrit. Voir ce dossier, corriger une instruction ou y lancer une commande ne devrait pas demander d'ouvrir à la main une fenêtre du Finder et un terminal — encore moins pour quelqu'un qui n'est pas développeur. Le panneau Agents montre donc le dossier de chaque agent, avec un éditeur et un terminal, où que l'agent tourne. Cette page explique les choix qui sont derrière ; les décisions sont dans l'ADR 0007 (en anglais), le comportement exact dans la référence.

Une seule idée du workspace, plusieurs endroits

Un agent peut tourner sur cet ordinateur, dans un conteneur Docker ou dans une sandbox Docker. Chaque endroit s'atteint différemment — le disque directement, docker exec ou sbx exec — mais l'arbre, l'éditeur et le terminal n'ont pas à s'en soucier. Sidekicks cache la différence derrière une seule notion de workspace : lister un dossier, lire, écrire, supprimer, suivre les changements, ouvrir un shell. Les mêmes tests tournent sur un dossier local, dans un vrai conteneur et dans une vraie sandbox : les trois se comportent pareil.

Côté conteneur, seules des commandes que les toutes petites images possèdent aussi sont utilisées (find, stat, cat de busybox). Un workspace qui ne marcherait qu'avec une distribution Linux complète surprendrait les utilisateurs des petites images dans lesquelles les agents sont souvent livrés.

Les sandboxes sont arrivées en dernier. sbx n'est pas disponible là où Sidekicks est développé : plutôt que de deviner, le côté sandbox a attendu que le propriétaire décrive sbx exec et lance la suite de tests sur une vraie sandbox. Elle s'est révélée calquée sur docker exec, et Sidekicks atteint les deux de la même façon, en n'utilisant que les options qu'ils partagent.

Modifier à côté d'un agent qui travaille

L'agent et l'utilisateur peuvent toucher le même fichier. Deux règles rendent cela sûr. D'abord, un fichier est toujours remplacé d'un seul coup (écrit à côté, puis déplacé à sa place) : l'agent ne lit jamais un demi-fichier. Ensuite, un enregistrement se souvient de la version du fichier qui a été ouverte ; si l'agent l'a modifié entre-temps, rien n'est écrasé en silence — l'utilisateur choisit entre sa version et celle de l'agent.

Supprimer sans regret

Une suppression depuis un outil graphique est censée être réversible. Sur cet ordinateur, les fichiers supprimés partent à la corbeille du système. Un conteneur ou une sandbox n'a pas de corbeille : la confirmation dit que la suppression est définitive plutôt que de faire semblant.

Des terminaux qui ne laissent rien derrière eux

Un terminal est un vrai shell derrière un pseudo-terminal : les programmes plein écran fonctionnent et la taille suit le panneau. Le fermer doit terminer ce qui y a été lancé — y compris les programmes mis en arrière-plan, qu'un simple « tuer le shell » rate. Dans un conteneur, il y a un piège : arrêter le client docker exec laisse le shell tourner dans le conteneur. Sidekicks termine donc toute la session du shell, côté conteneur aussi. Les deux cas ont été trouvés en testant, pas en lisant.

Les liens avec le reste

Les channels et ce que sait chaque agent : la conversation est la façon principale de travailler avec un agent ; le workspace est l'endroit où regarder quand il faut vérifier quelque chose.
Mémoire et modèles locaux : ouvrir un workspace ou un terminal ne démarre pas l'agent.
Architecture : internal/workspace atteint les dossiers, internal/app les expose à l'interface.

 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


# Workspaces et terminaux — explication

## De quoi s'agit-il ?

Un agent travaille dans un dossier : ses instructions (`AGENTS.md`), ses skills, ce qu'il écrit. Voir ce dossier, corriger une instruction ou y lancer une commande ne devrait pas demander d'ouvrir à la main une fenêtre du Finder et un terminal — encore moins pour quelqu'un qui n'est pas développeur. Le panneau Agents montre donc le dossier de chaque agent, avec un éditeur et un terminal, où que l'agent tourne. Cette page explique les choix qui sont derrière ; les décisions sont dans l'[ADR 0007](../../adr/0007-agent-workspaces.md) (en anglais), le comportement exact dans la [référence](../reference/agents-et-evenements.md#workspaces-milestone-m4).

## Une seule idée du workspace, plusieurs endroits

Un agent peut tourner sur cet ordinateur, dans un conteneur Docker ou dans une sandbox Docker. Chaque endroit s'atteint différemment — le disque directement, `docker exec` ou `sbx exec` — mais l'arbre, l'éditeur et le terminal n'ont pas à s'en soucier. Sidekicks cache la différence derrière une seule notion de workspace : lister un dossier, lire, écrire, supprimer, suivre les changements, ouvrir un shell. Les mêmes tests tournent sur un dossier local, dans un vrai conteneur et dans une vraie sandbox : les trois se comportent pareil.

Côté conteneur, seules des commandes que les toutes petites images possèdent aussi sont utilisées (`find`, `stat`, `cat` de busybox). Un workspace qui ne marcherait qu'avec une distribution Linux complète surprendrait les utilisateurs des petites images dans lesquelles les agents sont souvent livrés.

Les sandboxes sont arrivées en dernier. `sbx` n'est pas disponible là où Sidekicks est développé : plutôt que de deviner, le côté sandbox a attendu que le propriétaire décrive `sbx exec` et lance la suite de tests sur une vraie sandbox. Elle s'est révélée calquée sur `docker exec`, et Sidekicks atteint les deux de la même façon, en n'utilisant que les options qu'ils partagent.

## Modifier à côté d'un agent qui travaille

L'agent et l'utilisateur peuvent toucher le même fichier. Deux règles rendent cela sûr. D'abord, un fichier est toujours remplacé d'un seul coup (écrit à côté, puis déplacé à sa place) : l'agent ne lit jamais un demi-fichier. Ensuite, un enregistrement se souvient de la version du fichier qui a été ouverte ; si l'agent l'a modifié entre-temps, rien n'est écrasé en silence — l'utilisateur choisit entre sa version et celle de l'agent.

## Supprimer sans regret

Une suppression depuis un outil graphique est censée être réversible. Sur cet ordinateur, les fichiers supprimés partent à la corbeille du système. Un conteneur ou une sandbox n'a pas de corbeille : la confirmation dit que la suppression est définitive plutôt que de faire semblant.

## Des terminaux qui ne laissent rien derrière eux

Un terminal est un vrai shell derrière un pseudo-terminal : les programmes plein écran fonctionnent et la taille suit le panneau. Le fermer doit terminer ce qui y a été lancé — y compris les programmes mis en arrière-plan, qu'un simple « tuer le shell » rate. Dans un conteneur, il y a un piège : arrêter le client `docker exec` laisse le shell tourner dans le conteneur. Sidekicks termine donc toute la session du shell, côté conteneur aussi. Les deux cas ont été trouvés en testant, pas en lisant.

## Les liens avec le reste

- [Les channels et ce que sait chaque agent](channels-et-contexte.md) : la conversation est la façon principale de travailler avec un agent ; le workspace est l'endroit où regarder quand il faut vérifier quelque chose.
- [Mémoire et modèles locaux](memoire-et-modeles-locaux.md) : ouvrir un workspace ou un terminal ne démarre pas l'agent.
- [Architecture](architecture.md) : `internal/workspace` atteint les dossiers, `internal/app` les expose à l'interface.