Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/convertigo/c8oprj-convertigo-agent-bridge

Convertigo local agent bridge project
https://github.com/convertigo/c8oprj-convertigo-agent-bridge

Last synced: 15 days ago
JSON representation

Convertigo local agent bridge project

Awesome Lists containing this project

README 

          
# Convertigo Agent Bridge



Projet Convertigo dedie a l'integration locale des agents IA dans Convertigo

Studio.



L'objectif est d'exposer a l'assistant une interface HTTP/polling simple, sans

WebSocket, capable de piloter un agent CLI persistant comme `vibe-acp`. Le

projet `ConvertigoMCP` reste le serveur MCP appele par l'agent, mais il ne porte

pas le wrapper d'agent.



## Etat iteration 1



Le projet `ConvertigoAgentBridge` est un projet Convertigo autonome place dans :



```text

/Users/nicolas/git/c8oprj-convertigo-agent-bridge

```



Il expose les sequences publiques suivantes :



- `agent_python_setup` : verifie ou installe un runtime Python local au

  workspace Convertigo.

- `agent_codex_setup` : verifie ou installe le runtime Codex local.

- `agent_codex_start` : lance ou reutilise un `codex app-server` resident en

  stdio et cree ou reprend un thread Codex.

- `agent_codex_prompt` : envoie un prompt au thread Codex resident.

- `agent_codex_close` : ferme le handle Codex et arrete son app-server.

- `agent_vibe_setup` : verifie ou installe le runtime Vibe local.

- `agent_vibe_start` : lance `vibe-acp`, fait `initialize`, puis cree une

  session ACP.

- `agent_vibe_prompt` : envoie un prompt a la session ACP.

- `agent_events` : lit les evenements normalises par long-poll HTTP.

- `agent_status` : retourne les process vivants en memoire serveur, avec le PID

  quand le runtime l'expose.

- `agent_vibe_close` : ferme la session et arrete le process.

- `agent_sweep_expired` : nettoie les process abandonnes.



Les process sont gardes en memoire serveur via `context.server.set/get`. Le

handle courant est memorise dans la session HTTP pour permettre au chatbot de

continuer a appeler `agent_events` ou `agent_vibe_prompt` sans repasser le

handle a chaque requete.



Codex utilise `codex app-server --listen stdio://` par defaut. Le handle est

resident et `agent_codex_start` est idempotent : si le process existe deja, la

sequence retourne `already_running` au lieu de relancer Codex. Cela permet au

projet Assistant de prechauffer le serveur quand l'utilisateur reprend une

conversation.



Les app-servers Codex ont aussi un fichier PID sous

`/agents/codex/app-server-pids/.json`. Ce fichier permet de

nettoyer les process orphelins lorsque le registry memoire Convertigo est perdu.

`agent_codex_close` supprime le fichier PID ; `agent_codex_start` et

`agent_sweep_expired` peuvent fermer les PID expires qui ne sont plus lies a un

handle vivant.



## Appels HTTP



Les appels HTTP directs doivent passer le connecteur minimal `void`. Si

`mcpEndpoint` est vide, le bridge calcule l'endpoint depuis l'URL Convertigo

courante du moteur, puis ajoute `/api/mcp`. En local, les ports habituels sont

`18080` en Studio et `28080` en serveur.



Pour les exemples :



```text

BASE_URL=http://localhost:18080/convertigo

BRIDGE_URL=$BASE_URL/projects/ConvertigoAgentBridge/.json

```



Exemple de check runtime :



```bash

curl -sS "$BRIDGE_URL?__connector=void&__sequence=agent_vibe_setup&install=false&configure=false"

```



Exemple d'installation Python workspace-local :



```bash

curl -sS "$BRIDGE_URL?__connector=void&__sequence=agent_python_setup&install=true"

```



Exemple d'installation Codex workspace-local :



```bash

curl -sS "$BRIDGE_URL?__connector=void&__sequence=agent_codex_setup&install=true"

```



Exemple de demarrage ACP :



```bash

curl -sS --get \

  --data-urlencode '__connector=void' \

  --data-urlencode '__sequence=agent_vibe_start' \

  --data-urlencode 'handle=test-vibe-wrapper' \

  --data-urlencode 'cwd=/Users/nicolas/git' \

  --data-urlencode 'vibeHome=/Users/nicolas/git/agents/vibe/.vibe-home' \

  --data-urlencode 'env={"MISTRAL_API_KEY":"dummy"}' \

  "$BRIDGE_URL"

```



Le streaming cote UI se fait par polling :



```bash

curl -sS --get \

  --data-urlencode '__connector=void' \

  --data-urlencode '__sequence=agent_events' \

  --data-urlencode 'handle=test-vibe-wrapper' \

  --data-urlencode 'cursor=0' \

  --data-urlencode 'waitMs=1000' \

  "$BRIDGE_URL"

```



## Vibe ACP



La voie produit pour Vibe est ACP sur stdio, pas un wrapper batch

`vibe --continue`. ACP conserve le contexte dans le process vivant et remonte

les updates de raisonnement, reponse, outils, usage et permissions en temps

reel.



Le bootstrap Vibe fait :



1. Detection de Python, `uv`, `vibe` et `vibe-acp`, y compris les chemins

   usuels hors `PATH` du Studio (`~/.local/bin`, `/opt/homebrew/bin`,

   `/usr/local/bin`).

2. Si Python est absent et que `install=true`, installation d'un Python

   standalone dans `/agents/runtimes/python/`.

3. Avec `install=true`, creation de `/agents/vibe/.venv`, puis

   installation de `mistral-vibe` via `pip`.

4. Avec `configure=true`, ecriture de

   `/agents/vibe/.vibe-home/config.toml` avec le MCP Convertigo en

   HTTP. Si `mcpEndpoint` est vide, il est calcule depuis l'endpoint Convertigo

   courant.

5. Demarrage de `vibe-acp` avec ce `VIBE_HOME`, puis handshake ACP

   `initialize` + `session/new`.



Vibe 2.9.6 charge aussi sa config `config.toml`; le champ ACP `mcpServers` seul

ne suffit pas. Le setup local configure donc explicitement le MCP dans le

`VIBE_HOME` utilise par le process.



## Runtime Python workspace-local



`agent_python_setup` installe Python dans le workspace Convertigo, pas dans le

projet. Par defaut :



```text

/agents/runtimes/python/cpython-3.12.13-20260610-

```



Le setup utilise d'abord un Python deja disponible (`pythonPath`, `PYTHON`,

venv local, `~/.local/bin`, Homebrew, `python3`, `python`). Si aucun Python

n'est trouve et que `install=true`, il telecharge une archive

`python-build-standalone` via le client HTTP du moteur Convertigo, donc avec la

configuration proxy du serveur. Le telechargement peut etre remplace par :



- `pythonArchiveUrl` : URL directe de l'archive.

- `pythonAssetUrlPrefix` ou `pythonMirrorBaseUrl` : prefixe d'un miroir

  interne, avec support de `{tag}`.

- `pythonArchiveSha256` : controle optionnel de checksum.

- `allowPythonDownload=false` : mode diagnostic/offline, sans telechargement.



Les chemins optionnels (`installDir`, `pythonInstallDir`, `cwd`) peuvent etre

absolus ou relatifs. Quand ils sont relatifs, ils sont resolus depuis le

workspace Convertigo.



Cette installation est partageable par les providers. Les venvs restent separes

par agent, par exemple `/agents/vibe/.venv`.



## Runtime Codex workspace-local



`agent_codex_setup` detecte d'abord une CLI Codex existante (`codexPath`, puis

`/agents/codex/npm/node_modules/.bin/codex`, puis les chemins usuels

du poste). Si aucune CLI n'est trouvee et que `install=true`, il installe le

package npm `@openai/codex@latest` dans :



```text

/agents/codex/npm

```



L'installation utilise le mecanisme Node/npm du moteur Convertigo

(`ProcessUtils`), donc avec le repertoire Node du workspace et la configuration

proxy du serveur. Les options principales sont :



- `nodeVersion`, `nodeDir`, `npmPath` : overrides Node/npm.

- `allowNodeDownload=false` : mode diagnostic/offline, sans telechargement

  Node.

- `codexPackage`, `codexVersion` : package npm et version a installer.

- `playwrightMcpPackage`, `playwrightMcpVersion` : package Playwright MCP a

  installer a cote de la CLI Codex. Par defaut, le bridge installe

  `@playwright/mcp@latest`.

- `forceCodexInstall=true` : force la reinstall meme si une CLI est deja

  detectee.

- `forcePlaywrightInstall=true` : force la reinstall Playwright MCP.

- `skipPlaywrightInstall=true` : desactive l'installation Playwright MCP.



Le runtime Codex gere installe aussi `@playwright/mcp` dans le meme prefixe npm,

avec `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`. Aucun navigateur n'est telecharge par

defaut : Playwright MCP sert a s'attacher au JxBrowser visible expose par le

Studio via CDP (`browserDebugUrl`, `browserDevToolsWebSocketUrl` ou

`playwrightCdpEndpoint`). Le bridge configure alors le `codex-home/config.toml`

gere avec un serveur MCP Playwright stable. Pour un home de conversation,

l'endpoint CDP est ecrit dans les arguments du serveur Playwright MCP de ce home

et rafraichi a chaque viewer. Pour un home partage force, Playwright MCP reste

desactive par defaut afin de ne pas ouvrir un navigateur separe avec un endpoint

stale.



```toml

# The Studio JxBrowser CDP endpoint is written here because this Codex home is viewer-scoped.

# If a shared/user home is forced, Playwright MCP stays disabled to avoid opening an external browser.

[mcp_servers.playwright]

command = "npx"

args = ["--prefix", "/agents/codex/npm", "playwright-mcp", "--cdp-endpoint", "http://localhost:12345", "--shared-browser-context"]

startup_timeout_sec = 30

enabled = true

```



Les agents doivent utiliser les outils MCP Playwright exposes par Codex. Ils ne

doivent pas lancer de scripts ad hoc avec `require("playwright")` ni piloter un

navigateur par CLI hors du serveur MCP. Si le premier etat visible par les

outils navigateur est `about:blank` avant que `mobile-builder-open` ne retourne

`browserControlReady:true`, l'agent doit traiter le viewer comme encore en

chauffe et repoller le builder. Si les outils MCP Playwright/browser ne sont pas

exposes ou ne ciblent toujours pas le JxBrowser courant apres readiness, l'agent

doit signaler un probleme de configuration au lieu de contourner avec Node, CDP

brut ou un navigateur separe.



L'installation de la CLI ne configure pas l'authentification Codex. L'utilisateur

doit toujours disposer d'une session Codex valide dans le `CODEX_HOME` choisi,

ou utiliser le home Codex par defaut du poste.



## Isolation CODEX_HOME



Par defaut, Codex utilise un home par utilisateur sous

`/agents/codex/homes/users`. Quand un endpoint JxBrowser est fourni

pour Playwright MCP et qu'aucun scope n'est force par le client, le bridge passe

sur un home par conversation afin d'isoler la configuration runtime du viewer.

Les clients peuvent toujours forcer `codexHomeScope=user`, `conversation`,

`shared`, `default` ou fournir `codexHome` explicitement.



## Isolation VIBE_HOME



Le projet bridge est commun a plusieurs agents et plusieurs frontaux, mais

chaque process peut utiliser un `VIBE_HOME` separe. Le client choisit avec

`vibeHomeScope` :



- `shared` : home commun historique, `/agents/vibe/.vibe-home`.

- `user` : home par utilisateur, sous `/agents/vibe/homes/users`.

  `userId` est requis si le contexte Convertigo ne fournit pas deja un

  utilisateur authentifie.

- `conversation` : home par conversation, sous

  `/agents/vibe/homes/conversations` ou sous le home utilisateur si

  `userId` est fourni. Si `conversationId` est vide, un id est genere et garde

  dans la session HTTP.

- `vibeHome` explicite : prioritaire sur le scope, utile pour tests ou

  integrations avancees.



`projectId` peut etre fourni pour ajouter un niveau projet dans les homes

`user` et `conversation`. Les identifiants utilisateur/projet/conversation sont

hashes dans les chemins afin de ne pas exposer directement un email ou login

dans le filesystem.



Les credentials sont separes de ce choix de home. `agent_vibe_start` accepte

`credentialsPolicy` :



- `explicit` : uniquement les variables passees dans `env`, comportement par

  defaut.

- `user-home` : injecte les variables trouvees dans `~/.vibe/.env`.

- `vibe-home` : injecte les variables trouvees dans le `.env` du `VIBE_HOME`

  choisi.

- `auto` : tente `vibe-home`, puis `user-home`.



Les valeurs des variables ne sont jamais retournees dans les evenements ou les

status, seuls les noms de variables injectees le sont.



## Validation locale



Validation faite le 2026-06-15 sur le port hotfix local de developpement :



- `agent_vibe_setup install=false configure=false` detecte Python 3.14.5,

  `uv` 0.11.5, `vibe` 2.9.6 et `vibe-acp` 2.9.6.

- Le `VIBE_HOME` local valide est

  `/Users/nicolas/git/agents/vibe/.vibe-home`.

- Un `VIBE_HOME` explicite isole sous

  `/Users/nicolas/git/agents/vibe/homes/test-explicit/.vibe-home` est configure

  correctement et passe `initialize` + `session/new`.

- `agent_vibe_start` avec une cle factice `MISTRAL_API_KEY=dummy` passe

  `initialize` et `session/new` sans envoyer de prompt LLM.

- `agent_events` expose les evenements ACP initiaux, dont `acp/request`,

  `acp/response`, `commands/update` et `acp/session`.

- `agent_vibe_close` ferme la session et retire le process de la memoire

  serveur.



## Priorites suivantes



1. Ajouter une route/facade plus propre pour eviter de passer

   `__connector=void` dans les appels assistant.

2. Valider l'installation Python/Vibe sur un serveur sans Python preinstalle.

3. Valider un prompt Vibe ACP bout en bout avec MCP Convertigo actif et une

   vraie authentification Vibe.

4. Declencher `agent_sweep_expired` depuis un scheduler Convertigo.

5. Brancher l'UI assistant locale par polling HTTP.