firm-acp-bridge

Files (1)

• SKILL.md

SKILL.md (first lines)

# firm-acp-bridge

> ⚠️ Contenu généré par IA — validation humaine requise avant déploiement en production.

## Purpose

Ce skill rend le bridge ACP **résilient aux crashs** et les sessions agents autonomes
**pleinement fonctionnelles** en comblant les gaps découverts dans `openclaw/openclaw`.

**Gaps couverts :**
| Gap | Sévérité | Outil |
|-----|----------|-------|
| C4 — ACP sessions en mémoire uniquement (crash = perte) | CRITICAL | `acp_session_persist/restore` |
| H3 — Sessions spawn/cron sans provider env vars | HIGH | `fleet_session_inject_env` |
| H4 — Cron tools sur denylist sandbox | HIGH | `fleet_cron_schedule` |
| H5 — Race condition shared-workspace read/write | HIGH | `openclaw_workspace_lock` |

## Tools activés

```
acp_session_persist       — persiste run_id → gateway_session_key sur disque (C4)
acp_session_restore       — recharge sessions après crash/restart bridge (C4)
acp_session_list_active   — liste sessions ACP actives et stale (C4)
fleet_session_inject_env  — injecte provider env vars dans sessions non-main (H3)
fleet_cron_schedule       — planifie cron tasks sur session main (H4)
openclaw_workspace_lock   — advisory lock pour éviter les race conditions (H5)
```

## Protocole ACP Persistence (C4)

**Problème :** Si le bridge `openclaw acp` crashe ou est tué (OOM, reboot), tous les
mappings `run_id → gateway_session_key` en mémoire sont perdus. Les IDE integrations
(VS Code, Cursor) se reconnectent silencieusement à de nouvelles sessions.

### Intégration côté bridge (pattern d'appel)

**À chaque création de session ACP**, appeler immédiatement :

```json
{
  "tool": "acp_session_persist",
  "args": {
    "run_id": "<acp_run_id>",
    "gateway_session_key": "<gateway_key>",
    "metadata": {
      "ide": "vscode",
      "workspace": "/path/to/project",
      "created_by": "agent-name"
    }
  }
}
```

**Au démarrage du bridge** (après crash ou restart) :

```json
{
  "tool": "acp_session_restore",
  "args": { "max_age_hours": 24 }
}
```
→ Retourne les sessions récupérables + purge automatique des sessions > 24h stale.

**Pour monitorer :**

```json
{
  "tool": "acp_session_list_active",
  "args": { "include_stale": false }
}
```

### Décision d'architecture — ACP session store

| Option | Décision | Raison |
|--------|----------|--------|
| Redis | ❌ NON | Trop lourd pour single-operator, dépendance externe |
| SQLite | ❌ NON | Overkill pour des clés simples, migration schema |
| JSON file (atomic rename) | ✅ OUI | Zéro dépendance, atomic write (tmp + os.replace), léger |

## Autonomous Session Bootstrap (H3)

**Problème :** Les sessions spawned via `sessions_spawn` ou cron n'ont pas accès aux
env vars des providers configurés (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).
Tout appel LLM dans une session non-main échoue silencieusement.

### Séquence obligatoire avant sessions_spawn

**Étape 1 — Validation dry_run (vérifier les clés sans envoyer) :**

```json
{
  "tool": "fleet_session_inject_env",
  "args": {
    "env_vars": {
      "ANTHROPIC_API_KEY": "<your_key>",
      "OPENCLAW_MODEL": "claude-3-5-sonnet-20241022"
    },
    "dry_run": true
  }
}
```
→ Vérifie que les clés passent l'allowlist. Si `rejected` non vide, les clés sont invalides.

**Étape 2 — Injection effective avant spawn :**

```json
{
  "tool": "fleet_session_inject_env",
  "args": {
    "env_vars": {
      "ANTHROPIC_API_KEY": "<your_key>",
      "OPENCLAW_MODEL": "claude-3-5-sonnet-20241022"
    },
    "filter_tags": ["engineering", "quality"]
  }
}
```

From romainsantoli-web/setup-vs-agent-firm, MIT.

More from romainsantoli-web/setup-vs-agent-firm