Skip to main content
Glama
README.md
# mcp-agent-harness

Un provider de [mcp-broker](https://github.com/pandaGaume/mcp-broker) qui publie les agents de code locaux, Codex d'abord puis Claude Code, chacun dans son propre slot (`codex`, `claude`). Les slots partagent un contrat MCP commun, asynchrone par construction : démarrer un thread, le suivre par abonnement ou par long-poll, répondre aux approbations, le reprendre depuis un autre client.

**Statut : lots 1 et 2a.** Le contrat `agent/v0`, le journal, les approbations, les propriétés, le raccordement au broker, l'état dans mcp-persistence, les secrets dans mcp-vault et l'adaptateur **Codex** (App Server, connexion par clé ou par ChatGPT) sont faits et testés. Restent le lot 2b (fork, reprise des threads après redémarrage du provider), Claude (lot 3) et l'autorisation (lot 4). Voir l'[ADR-0001](docs/adr/0001-agents-de-code-comme-slots.md).

## En bref

- Un **provider**, pas un client : il occupe des slots, et les clients MCP s'y connectent en `http://<hôte>/<slot>/mcp`.
- **Aucun appel bloquant** : le broker coupe une requête au bout de 60 s, alors qu'un turn d'agent dure des minutes.
- Le **provider est la source de vérité** : un `threadId` explicite, indépendant de toute session MCP.
- Les **approbations sont un état** : le broker ne relaie pas les requêtes du serveur vers le client.
- Les **valeurs par défaut sont des propriétés** réglables par contrat, dans des bornes fixées par l'opérateur.
- **Hors de `_all`**, et sur un slot protégé : ce provider exécute du code sur le poste.

## Le slot `codex`

Codex 0.170.0 (`npm install -g @openai/codex@0.170.0`). Une autre version est refusée tant qu'elle n'est pas testée, sauf `codex.allowUntestedVersion`.

Le slot a **son propre `CODEX_HOME`** (`codex.home`), jamais votre `~/.codex` : il ne touche ni à votre configuration ni à votre connexion Codex personnelles. Deux façons de le connecter :

**Avec votre compte ChatGPT** ([examples/codex.chatgpt.config.json](examples/codex.chatgpt.config.json)). Démarrez le provider, puis, depuis un client MCP connecté au slot :

1. `codex_login_start { "method": "browser" }` rend `authUrl`. Ouvrez-la dans un navigateur **sur la machine où tourne le provider** : le retour de connexion arrive sur un port local de cette machine. Ou `{ "method": "deviceCode" }` : une URL et un code à saisir, depuis n'importe quel appareil.
2. `codex_account` confirme : `loggedIn: true`, le compte, la formule.

Codex garde les jetons dans `codex.home` (`"store": "file"`) ou dans le trousseau du système (`"keyring"`). La connexion survit aux redémarrages. `codex_logout` la retire.

**Avec une clé API dans mcp-vault** ([examples/codex.vault.config.json](examples/codex.vault.config.json)). La clé est lue dans le vault à chaque démarrage de Codex et lui est passée par stdio. Codex tourne alors avec un stockage éphémère : la clé n'est jamais écrite sur disque, ni dans un environnement que les commandes de l'agent pourraient lire. `codex_login_start` est refusé dans ce mode : on change la clé dans le vault.

Dans les deux cas, Codex ne reçoit jamais le secret du provider ni le bearer client : le provider les retire de son environnement.

**Questions de Codex.** Les formulaires des serveurs MCP que Codex utilise sont relayés par défaut. Les questions en milieu de turn demandent une fonction que Codex 0.170.0 marque « under development » : `"enableFeatures": ["default_mode_request_user_input"]` dans la section `codex`. Sans elle, Codex pose ses questions dans son message de fin de turn.

`codex.command` vaut `codex` (sur le PATH) par défaut. Sous Windows, si `codex` n'est qu'un raccourci `.cmd`, préférez le chemin du `bin/codex.js` du paquet npm, que le provider lance avec son propre Node.

| tool natif | rôle |
|---|---|
| `codex_account` | mode de connexion, compte, connexion en cours, résultat de la dernière ; jamais de secret |
| `codex_login_start` | connexion ChatGPT : `browser` ou `deviceCode` |
| `codex_login_cancel`, `codex_logout` | annule la connexion en cours ; déconnecte le slot |
| `codex_thread_archive` | archive un thread dans Codex ; il ne prend plus de turn |

## Essayer avec le moteur factice

Node 22 ou plus récent. Un broker sur le port 3000 :

```powershell
npx @cyanmycelium/mcp-broker
```

Le provider, depuis ce dépôt :

```powershell
npm install
```

```powershell
npm run build
```

```powershell
node dist/bin.js --config examples/fake.config.json
```

Le slot est alors `http://127.0.0.1:3000/fake/mcp`. Dans Claude Code (`.mcp.json`) :

```json
{
    "mcpServers": {
        "fake-agent": { "type": "http", "url": "http://127.0.0.1:3000/fake/mcp" }
    }
}
```

Le moteur factice répète le prompt. Un prompt qui contient `run`, `command` ou `approval` demande d'abord une approbation.

## Le contrat `agent/v0`

| tool | rôle |
|---|---|
| `agent_start` | démarre un thread sur un répertoire ; rend `threadId` tout de suite |
| `agent_send` | nouveau turn sur un thread au repos |
| `agent_wait` | long-poll : les événements après `sinceSeq`, dès qu'il y en a, ou au bout de `timeoutMs` |
| `agent_approve` | répond à une approbation en attente (`accept`, `acceptForSession`, `decline`) |
| `agent_answer` | répond à une question de l'agent en attente (état `awaiting_input`) |
| `agent_interrupt` | arrête le turn en cours ; le thread reste |
| `agent_list` | les threads du slot |
| `agent_property_get` / `agent_property_set` | lit et règle les propriétés, par slot ou par thread |

| ressource | contenu |
|---|---|
| `agent://threads` | la liste des threads |
| `agent://threads/{threadId}` | un thread : état, approbations et questions en attente, derniers événements, `lastSeq` |
| `agent://properties` | les propriétés : défaut, bornes, portées, valeur du slot |

Les trois ressources sont abonnables : chaque changement envoie `notifications/resources/updated` sur l'URI exacte. Un refus est un résultat `isError` lisible par le modèle, `{ error: { code, message, detail? } }` ; les codes sont dans l'ADR.

### Converser avec l'agent

Le client d'un slot est souvent un autre agent. Deux façons de lui répondre :

- **À la fin d'un turn**, l'agent a dit quelque chose, parfois une question : `agent_send` lui répond, c'est le turn suivant.
- **Au milieu d'un turn**, l'agent pose une question et attend : le thread passe en `awaiting_input`, la question est dans `pendingQuestions` (ses options, ou le formulaire d'un serveur MCP, ou une page à visiter), et `agent_answer` y répond. Sans réponse, elle est déclinée au bout de `inputTimeoutMs`.

Une question marquée secrète n'est pas relayée, sauf `allowSecretQuestions` : passez plutôt le secret par mcp-vault.

Boucle type d'un client :

```text
agent_start { cwd, prompt }                  -> { threadId, turnId, state: "running" }
agent_wait  { threadId, sinceSeq: 0 }        -> { events, lastSeq: 3, state: "awaiting_approval", pendingApprovals }
agent_approve { threadId, approvalId, decision: "accept" }
agent_wait  { threadId, sinceSeq: 3 }        -> { events, lastSeq: 7, state: "idle" }
```

## Configuration

Le fichier passé à `--config`. Les chemins relatifs partent du fichier. Une clé inconnue arrête le démarrage.

| clé | rôle |
|---|---|
| `broker` | URL WebSocket du broker. Défaut `ws://127.0.0.1:3000`. Le provider se connecte à `<broker>/provider/<slot>` |
| `slot` | slot publié. Défaut : le nom du moteur |
| `engine` | `codex`, ou `fake` pour essayer le contrat sans agent |
| `codex` | avec `engine: "codex"` : `command`, `home` (le `CODEX_HOME` du slot, requis), `auth` (`{ "mode": "apiKey", "apiKey": <référence vault> }` ou `{ "mode": "chatgpt", "store"?: "file" \| "keyring" }`), `model`, `allowUntestedVersion`, `requestTimeoutMs`, `enableFeatures` (fonctions de Codex à activer) |
| `secretEnv` | **nom** de la variable d'environnement qui contient le secret du provider. Un `secret` en clair est refusé |
| `clientTokenEnv` | **nom** de la variable qui contient le bearer avec lequel le harness appelle les slots `persistence` et `vault`. Requis par `state.persistence` et `credentials` |
| `workspaceRoots` | répertoires où un thread peut travailler. Un `cwd` hors de ces racines est refusé |
| `sandbox`, `approvalPolicy` | `{ default, ceiling }` : ce qu'un client obtient sans rien demander, et le plus qu'il peut demander |
| `properties` | bornes par propriété : `{ "<nom>": { default?, min?, max? } }` |
| `waitCeilingMs` | plafond de `waitMaxMs`. Défaut 50 000. **Doit rester sous le `providerRequestTimeoutMs` du broker** (60 000 par défaut), que le provider ne peut pas lire |
| `state` | où les propriétés de portée `slot` survivent au redémarrage : `{ "file": "<chemin>" }` (développement, poste isolé) ou `{ "persistence": { slot?, namespace? } }` (un document mcp-persistence). Absent : en mémoire |
| `credentials` | `{ "vault": { slot?, prefix?, vaultKid? } }` : le slot mcp-vault d'où viennent les secrets des moteurs, et le préfixe sous lequel le harness peut lire (`agent-harness` par défaut) |
| `allowSecretQuestions` | relaie les questions que l'agent marque secrètes. Désactivé par défaut : leur réponse traverserait le broker en clair |
| `engineSecrets` | variable d'environnement du moteur vers référence vault : `{ "OPENAI_API_KEY": { "slot": "vault", "path": "agent-harness/openai", "key": "apiKey" } }`. Résolues au démarrage ; une seule manquante arrête le démarrage |

### Avec les slots de la famille

En production, l'état et les secrets passent par les slots mcp-persistence et mcp-vault du même broker (ADR, D12). Voir [examples/family.config.json](examples/family.config.json). Il faut installer les deux paquets, dépendances optionnelles de celui-ci :

```powershell
npm install @cyanmycelium/mcp-persistence @cyanmycelium/mcp-vault
```

- **État** : un document `properties.<slot>` dans le namespace `agent-harness`. Chaque écriture porte la révision lue : si une autre instance a écrit entre-temps, la modification est refusée (`state_conflict`) et l'état rechargé, jamais écrasé. Si le slot est injoignable, rien ne change (`store_unavailable`).
- **Secrets** : lus scellés de bout en bout, pour une paire de clés neuve à chaque processus. Le broker ne voit que du chiffré, et les valeurs ne vont qu'au moteur.
- **Politique du broker** pour l'identité du bearer client : `persistence.read` et `persistence.write` sur son namespace, `vault.read` sous son préfixe, rien d'autre.

| propriété | défaut | bornes par défaut | portées |
|---|---|---|---|
| `approvalTimeoutMs` | 900 000 | 10 000 à 86 400 000 | slot, thread |
| `inputTimeoutMs` | 900 000 | 10 000 à 86 400 000 | slot, thread |
| `waitDefaultMs` | 25 000 | 1 000 à `waitMaxMs` | slot, thread |
| `waitMaxMs` | 45 000 | 1 000 à `waitCeilingMs` | slot |
| `journalMaxEvents` | 1 000 | 100 à 100 000 | slot |

## Sécurité

Ce slot fait exécuter du code sur le poste. Avec le moteur factice, rien ne s'exécute vraiment ; avec Codex (lot 2), si. Avant de brancher un vrai moteur :

- un broker lié à `127.0.0.1` ;
- l'authentification client active sur le broker, et ce slot déclaré protégé (`authorization.protectedSlots`) ;
- une identité de provider dans le fichier de sécurité du broker, et son secret dans `secretEnv` ;
- les clés des moteurs dans mcp-vault (`engineSecrets`), pas dans l'environnement du provider ;
- des `workspaceRoots` aussi étroits que possible.

Une montée WebSocket ne passe par aucun contrôle d'origine, et les endpoints HTTP sont anonymes tant que l'authentification client est coupée.

## Développement

```powershell
npm test
```

Les tests tournent sur les sources, contre un vrai broker (`startTestBroker`) pour le bout en bout. `npm run typecheck`, `npm run format` et `npm run build` complètent ce que fait la CI.

## Documents

- [ADR-0001 : les agents de code locaux comme slots du broker](docs/adr/0001-agents-de-code-comme-slots.md) : contexte, contraintes du broker, décisions, contrat `agent/v0`, erreurs, options écartées, lots.