Adapter Setup Kit

Adapter setup kit (catalogue, setup, tunnels)

L'amont de l'orchestration : avant de agent_start, il faut un adapter ready ; pour piloter un agent distant ou exposer un service, il faut un tunnel. Ce skill couvre l'inventaire (list_*), la config des providers sensibles (setup_*), et l'exposition réseau (tunnel_create). Les autres skills d'orchestration supposent tout ça déjà en place.

Les trois familles d'adapters

Un même socle (@agentproto/adapter-kit) catalogue trois familles, chacune avec son list_* :

• Agents CLI — adapter_list (claude-code, hermes, opencode, codex,

openclaw…). Ce que tu spawnes.

• Tunnels — list_tunnel_adapters (cloudflare-quick, cloudflare-named).

Comment tu exposes.

• Navigateurs — browser_adapter_list (agents qui pilotent un navigateur).

Tous renvoient un statut uniforme à 3 états :

• supported = connu mais pas installé (ex. opencode, codex →

version: "not installed"). Il faut installer le package (@agentproto/adapter-).

• available = installé mais setup non fait (ex. cloudflare-named :

requiresAuth → besoin de credentials).

• ready = installé et configuré, utilisable tout de suite (ex.

claude-code, hermes, cloudflare-quick).

Règle d'or : appelle le list_* AVANT de spawner/ouvrir. Ne devine pas ce qui est installé — un agent_start sur un adapter supported (pas installé) échoue.

Pattern 1 — Cataloguer (le check d'amont)

adapter_list renvoie pour chaque agent : slug, name, version, protocol (acp/…), streaming, packageName, models (la liste des modèles connus de l'adapter), status, hint. Exemple vécu : claude-code et hermes sont ready ; opencode / codex / openclaw sont supported (version: "not installed"). Utilise models pour proposer un choix de modèle au spawn, et status pour ne proposer que le ready.

list_tunnel_adapters renvoie en plus un bloc capabilities par provider : stableUrl, autostart, customDomain, requiresAuth, hasApi — c'est ce qui décide quel provider répond au besoin (URL stable ? relance au boot ?).

Pattern 2 — Configurer un provider sensible (setup_*)

Un provider available qui demande des creds se configure sans jamais exposer le secret :

setup_tunnel_provider({ slug: "cloudflare-named",
  value: "{\"hostname\":\"app.example.com\",\"tunnelId\":\"\",\"credentialsFile\":\"\"}" })

• value est une chaîne JSON (multi-champs) — le kit gère les credentials

multi-champs via une seule string sérialisée.

• Sensible par construction : stocké en 0600, jamais ré-affiché dans

un résultat de tool ni loggé. Ne t'attends pas à le relire — si tu dois vérifier, regarde le passage available → ready via list_tunnel_adapters, pas la valeur.

• Après setup réussi, le provider passe available → ready.

(Le même pattern setup_* multi-champs/sensible s'applique aux autres familles qui demandent des creds — c'est une primitive du kit, pas propre aux tunnels.)

Pattern 3 — Exposer un port en HTTPS public (tunnel_create)

Deux backends, choisis selon que tu veux jetable ou stable :

• quick (défaut, zéro credential) : Cloudflare Quick Tunnel, URL

éphémère *.trycloudflare.com régénérée à chaque run. Parfait pour un test ponctuel / un webhook receiver jetable. `` tunnel_create({ targetPort: 3000 }) // → https://xxxx.trycloudflare.com ``

• named (BYO, stable) : un tunnel cloudflared que tu as provisionné

une fois (cloudflared tunnel create + route dns), lié à un hostname stable qui survit aux restarts. Passe hostname + tunnelId, et autostart: true pour que le daemon le relance au boot.

`` tunnel_create({ targetPort: 8080, provider: "named", hostname: "app.example.com", tunnelId: "", autostart: true }) ``

• targetHost défaut 127.0.0.1 (mets localhost seulement si la cible est en

IPv6). tunnel_create rend le TunnelDescriptor quand cloudflared est prêt (typiquement d'abord → repérer ready vs available vs supported`

• [ ] Installer le package si supported (@agentproto/adapter-)
• [ ] setup_* si available + requiresAuth (value = JSON multi-champs,

sensible)

• [ ] Confirmer le passage à ready via un list_* (pas en relisant le secret)
• [ ] Tunnel : quick pour jetable, named (+autostart) pour stable
• [ ] tunnel_list avant d'ouvrir un doublon ; tunnel_stop en fin de vie

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentproto
• Source: agentproto/ts
• License: Apache-2.0
• Homepage: https://agentproto.sh

Install and usage instructions live in the source repository linked above.