Outils du client en Node.js : un client qui prête un outil à mm

 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

# Outils du client en Node.js : un client qui prête un outil à mm

*[English version](README.en.md)*

`client.js` est un client ACP de `mm -acp` qui propose à l'agent un de ses propres outils, `host_info` : une fonction JavaScript qui donne le système d'exploitation, le CPU, la mémoire ou la durée de fonctionnement de la machine où tourne le client. L'agent n'a pas de shell (`bashTool: false`) : l'outil du client est son seul moyen de savoir quoi que ce soit sur la machine. mm découvre l'outil par ACP et le modèle l'appelle comme les siens, sous le nom `client_host_info` (ticket 202, le protocole est dans [Outils du client ACP](../../docs/fr/reference/acp-client-tools.md)).

Aucune dépendance : Node.js 20 ou plus, `node:child_process`, `node:readline`, `node:os`.

## Fichiers

| Fichier | |
|---|---|
| `client.js` | le client : lance mm, annonce l'outil, pose une question, répond aux appels de l'outil, affiche la réponse |
| `agent.yaml` | l'agent : Qwen3.5 4B sur llmman, pas de bash, `yolo: true`, `acp.clientTools.discovery: meta` |
| `agent-request.yaml` | le même agent avec `acp.clientTools.discovery: request` |

## Le lancer

Il faut un mm compilé avec le ticket 202 (`acp.clientTools`), et llmman avec le modèle :

```bash
llmman pull hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
llmman serve

cd demo.acp.sdk/client-tools-nodejs
node client.js                                                    # question par défaut, découverte "meta"
node client.js "How much memory is free on my machine?"           # votre question
node client.js --request "Which CPU does my machine have?"        # découverte "request"
```

`mm` doit être dans le PATH, ou désigné par `MM_BIN` (`MM_BIN=/chemin/vers/mm node client.js`).

Sortie attendue (les valeurs sont celles de votre machine) :

```
[acp] client tools (meta): client_host_info
[client] discovery: meta, session 20261110-230430-6df8f9dd
❓ What operating system does my machine run, and how much memory does it have?

🛠️  client: host_info
🛠️  client: host_info
[client] host_info {"topic":"os"} (session 20261110-230430-6df8f9dd)
[client] host_info {"topic":"memory"} (session 20261110-230430-6df8f9dd)
   │ Linux 7.0.14 (linux/arm64), host name claude-mini-me
   │ 15.0 GiB free of 15.8 GiB
Your machine runs Linux (version 7.0.14 on ARM64) and has 15.8 GiB of total memory, with 15.0 GiB currently free.

[end_turn]
```

- `[acp] …` est la ligne stderr de mm lui-même : il a vu l'outil. En mode `--request`, elle est précédée de `[client] list requested for session …` : mm a demandé la liste pendant qu'il ouvrait la session.
- `[client] host_info …` est affiché par le client quand mm appelle l'outil : les arguments du modèle, et la session lue dans `_meta`.
- `🛠️` et `│` sont les notifications `session/update` de mm : l'appel d'outil et son résultat, comme un éditeur les afficherait.

## Comment fait le client

| Étape | Dans `client.js` |
|---|---|
| décrire l'outil | `hostInfoTool` : `name`, `description`, `method` (`_demo.minime/host_info`, une méthode d'extension ACP), `inputSchema` |
| l'annoncer | `initialize` avec `clientCapabilities._meta["org.mini-me/tools"]` : la liste (`meta`) ou `true` (`request`) |
| donner la liste (`request` seulement) | répondre à `_org.mini-me/tools/list` avec `{tools: [hostInfoTool]}` |
| exécuter un appel | répondre à la requête `_demo.minime/host_info` : les arguments sont au premier niveau de `params`, la session dans `params._meta["org.mini-me/sessionId"]` ; la réponse est `{content: [{type: "text", text}]}`, ou `isError: true` avec un message que le modèle peut lire |
| confirmer un appel (`yolo: false`) | répondre à `session/request_permission` : autoriser les titres qui commencent par `client: `, refuser le reste |
| tout ce que mm demande d'autre | erreur JSON-RPC `-32601` (method not found) |

## À essayer

- Mettre `yolo: false` dans `agent.yaml` : chaque appel passe d'abord par `session/request_permission`, et le client affiche `[client] permission for "client: host_info": allowed`.
- Croiser les modes : remettre `discovery: meta` dans `agent-request.yaml` et lancer `node client.js --request`. Le client n'annonce que `true`, mm attend la liste elle-même : il affiche `[acp] client tools: "org.mini-me/tools" is not a list of tools; …` et le modèle n'a pas d'outil.
- Ajouter un second outil : une entrée de plus dans la liste, un `case` de plus dans `onRequest`.

## Mesuré (2026-11-10, dans le sandbox de développement, Linux arm64, llmman avec Qwen3.5 4B, mm compilé depuis la branche `feature/acp-client-tools`)

| Lancement | Résultat |
|---|---|
| `node client.js` | deux appels (`os`, `memory`), réponse construite à partir des deux |
| `node client.js --request "Which CPU does my machine have, and since when is it up?"` | liste demandée à `session/new`, deux appels (`uptime`, `cpu`), réponse construite à partir des deux |
| `yolo: false` | permission demandée et accordée, puis l'appel, puis la réponse |

Lancé aussi par l'auteur sur macOS (2026-11-10), avec mm recompilé depuis la branche : ça fonctionne.