{
  "schemaVersion": "1.0",
  "item": {
    "slug": "firm-acp-bridge",
    "name": "Firm Acp Bridge",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/romainsantoli-web/firm-acp-bridge",
    "canonicalUrl": "https://clawhub.ai/romainsantoli-web/firm-acp-bridge",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/firm-acp-bridge",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=firm-acp-bridge",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/firm-acp-bridge"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/firm-acp-bridge",
    "agentPageUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent",
    "manifestUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "firm-acp-bridge",
        "body": "⚠️ Contenu généré par IA — validation humaine requise avant déploiement en production."
      },
      {
        "title": "Purpose",
        "body": "Ce skill rend le bridge ACP résilient aux crashs et les sessions agents autonomes\npleinement fonctionnelles en comblant les gaps découverts dans openclaw/openclaw.\n\nGaps couverts :\n\nGapSévéritéOutilC4 — ACP sessions en mémoire uniquement (crash = perte)CRITICALacp_session_persist/restoreH3 — Sessions spawn/cron sans provider env varsHIGHfleet_session_inject_envH4 — Cron tools sur denylist sandboxHIGHfleet_cron_scheduleH5 — Race condition shared-workspace read/writeHIGHopenclaw_workspace_lock"
      },
      {
        "title": "Tools activés",
        "body": "acp_session_persist       — persiste run_id → gateway_session_key sur disque (C4)\nacp_session_restore       — recharge sessions après crash/restart bridge (C4)\nacp_session_list_active   — liste sessions ACP actives et stale (C4)\nfleet_session_inject_env  — injecte provider env vars dans sessions non-main (H3)\nfleet_cron_schedule       — planifie cron tasks sur session main (H4)\nopenclaw_workspace_lock   — advisory lock pour éviter les race conditions (H5)"
      },
      {
        "title": "Protocole ACP Persistence (C4)",
        "body": "Problème : Si le bridge openclaw acp crashe ou est tué (OOM, reboot), tous les\nmappings run_id → gateway_session_key en mémoire sont perdus. Les IDE integrations\n(VS Code, Cursor) se reconnectent silencieusement à de nouvelles sessions."
      },
      {
        "title": "Intégration côté bridge (pattern d'appel)",
        "body": "À chaque création de session ACP, appeler immédiatement :\n\n{\n  \"tool\": \"acp_session_persist\",\n  \"args\": {\n    \"run_id\": \"<acp_run_id>\",\n    \"gateway_session_key\": \"<gateway_key>\",\n    \"metadata\": {\n      \"ide\": \"vscode\",\n      \"workspace\": \"/path/to/project\",\n      \"created_by\": \"agent-name\"\n    }\n  }\n}\n\nAu démarrage du bridge (après crash ou restart) :\n\n{\n  \"tool\": \"acp_session_restore\",\n  \"args\": { \"max_age_hours\": 24 }\n}\n\n→ Retourne les sessions récupérables + purge automatique des sessions > 24h stale.\n\nPour monitorer :\n\n{\n  \"tool\": \"acp_session_list_active\",\n  \"args\": { \"include_stale\": false }\n}"
      },
      {
        "title": "Décision d'architecture — ACP session store",
        "body": "OptionDécisionRaisonRedis❌ NONTrop lourd pour single-operator, dépendance externeSQLite❌ NONOverkill pour des clés simples, migration schemaJSON file (atomic rename)✅ OUIZéro dépendance, atomic write (tmp + os.replace), léger"
      },
      {
        "title": "Autonomous Session Bootstrap (H3)",
        "body": "Problème : Les sessions spawned via sessions_spawn ou cron n'ont pas accès aux\nenv vars des providers configurés (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).\nTout appel LLM dans une session non-main échoue silencieusement."
      },
      {
        "title": "Séquence obligatoire avant sessions_spawn",
        "body": "Étape 1 — Validation dry_run (vérifier les clés sans envoyer) :\n\n{\n  \"tool\": \"fleet_session_inject_env\",\n  \"args\": {\n    \"env_vars\": {\n      \"ANTHROPIC_API_KEY\": \"<your_key>\",\n      \"OPENCLAW_MODEL\": \"claude-3-5-sonnet-20241022\"\n    },\n    \"dry_run\": true\n  }\n}\n\n→ Vérifie que les clés passent l'allowlist. Si rejected non vide, les clés sont invalides.\n\nÉtape 2 — Injection effective avant spawn :\n\n{\n  \"tool\": \"fleet_session_inject_env\",\n  \"args\": {\n    \"env_vars\": {\n      \"ANTHROPIC_API_KEY\": \"<your_key>\",\n      \"OPENCLAW_MODEL\": \"claude-3-5-sonnet-20241022\"\n    },\n    \"filter_tags\": [\"engineering\", \"quality\"]\n  }\n}\n\nÉtape 3 — Spawn la session (via Gateway direct) :\n\n{\n  \"method\": \"sessions_spawn\",\n  \"params\": {\n    \"agent\": \"engineering\",\n    \"reply_session\": \"main\"\n  }\n}"
      },
      {
        "title": "Clés autorisées (allowlist intégrée)",
        "body": "ANTHROPIC_API_KEY | OPENAI_API_KEY | OPENROUTER_API_KEY | GEMINI_API_KEY\nOPENCLAW_MODEL | OPENCLAW_PROVIDER | OPENCLAW_MAX_TOKENS\nCLAW_MODEL | CLAW_PROVIDER | PROXY_URL | CUSTOM_*\n\nJamais dans les logs — les valeurs sont masquées avec ****{last4}."
      },
      {
        "title": "Cron Outside Sandbox (H4)",
        "body": "Problème : cron tools sont sur la denylist dans les sessions Docker sandbox.\nTout workflow autonome planifié dans un container non-main est bloqué.\n\nSolution : Planifier sur la session main (accès hôte) via fleet_cron_schedule.\n\n{\n  \"tool\": \"fleet_cron_schedule\",\n  \"args\": {\n    \"command\": \"node scripts/daily-report.js\",\n    \"schedule\": \"0 9 * * 1-5\",\n    \"session\": \"main\",\n    \"description\": \"Daily business report — Monday to Friday 9h\"\n  }\n}\n\nUtiliser fleet_cron_schedule quand :\n\n✅ La tâche est un script léger et déterministe\n✅ La tâche ne nécessite pas d'isolation sécurité\n✅ La command passe l'allowlist [a-zA-Z0-9 /._-=]+\n\nUtiliser sessions_spawn (session non-main) quand :\n\n✅ La tâche implique du code non vérifié / externe\n✅ Isolation sécurité requise (sandbox Docker)\n✅ La tâche peut se déclencher ad-hoc (pas planifiée)"
      },
      {
        "title": "Workspace Locking (H5)",
        "body": "Problème : Race condition documentée (#29947) sur shared-workspace read/modify/write.\nPlusieurs sessions agent peuvent corrompre la même ressource partagée."
      },
      {
        "title": "Pattern acquire / work / release",
        "body": "// 1. Acquérir le lock\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"acquire\",\n    \"owner\": \"engineering-session-001\",\n    \"timeout_s\": 30\n  }\n}\n\n// 2. Faire le travail (read → modify → write)\n// ... vos opérations sur la ressource ...\n\n// 3. Libérer le lock\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"release\",\n    \"owner\": \"engineering-session-001\"\n  }\n}\n\nVérifier le statut d'un lock :\n\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"status\",\n    \"owner\": \"any\"\n  }\n}"
      },
      {
        "title": "Règles",
        "body": "Le lock est advisory (pas kernel-level) — tous les agents doivent coopérer\ntimeout_s max = 300s. Si lock non acquis → ok: false + current_owner\nToujours release dans un bloc try/finally pour éviter les locks orphelins\nUn lock expired ne se libère pas automatiquement — utiliser acp_session_restore pour purger les owners stale"
      },
      {
        "title": "Monitoring de santé ACP",
        "body": "Flux de monitoring recommandé (à exécuter périodiquement) :\n\nacp_session_list_active → sessions stale > 2h → acp_session_restore(max_age_hours=2) → recheck\n\nSi restored: 0 et purged > 0 après un intervalle normal → le bridge a crashé et les\nsessions ont été perdues → notifier via firm_export_slack_digest.\n\nOpenClaw gaps : C4 (ACP in-memory), H3 (#29886 isolated sessions no provider env), H4 (#29921 cron sandbox denylist), H5 (#29947 race condition)"
      },
      {
        "title": "💎 Support",
        "body": "Si ce skill vous est utile, vous pouvez soutenir le développement :\n\nDogecoin : DQBggqFNWsRNTPb6kkiwppnMo1Hm8edfWq"
      }
    ],
    "body": "firm-acp-bridge\n\n⚠️ Contenu généré par IA — validation humaine requise avant déploiement en production.\n\nPurpose\n\nCe 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.\n\nGaps couverts :\n\nGap\tSévérité\tOutil\nC4 — ACP sessions en mémoire uniquement (crash = perte)\tCRITICAL\tacp_session_persist/restore\nH3 — Sessions spawn/cron sans provider env vars\tHIGH\tfleet_session_inject_env\nH4 — Cron tools sur denylist sandbox\tHIGH\tfleet_cron_schedule\nH5 — Race condition shared-workspace read/write\tHIGH\topenclaw_workspace_lock\nTools activés\nacp_session_persist       — persiste run_id → gateway_session_key sur disque (C4)\nacp_session_restore       — recharge sessions après crash/restart bridge (C4)\nacp_session_list_active   — liste sessions ACP actives et stale (C4)\nfleet_session_inject_env  — injecte provider env vars dans sessions non-main (H3)\nfleet_cron_schedule       — planifie cron tasks sur session main (H4)\nopenclaw_workspace_lock   — advisory lock pour éviter les race conditions (H5)\n\nProtocole ACP Persistence (C4)\n\nProblè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.\n\nIntégration côté bridge (pattern d'appel)\n\nÀ chaque création de session ACP, appeler immédiatement :\n\n{\n  \"tool\": \"acp_session_persist\",\n  \"args\": {\n    \"run_id\": \"<acp_run_id>\",\n    \"gateway_session_key\": \"<gateway_key>\",\n    \"metadata\": {\n      \"ide\": \"vscode\",\n      \"workspace\": \"/path/to/project\",\n      \"created_by\": \"agent-name\"\n    }\n  }\n}\n\n\nAu démarrage du bridge (après crash ou restart) :\n\n{\n  \"tool\": \"acp_session_restore\",\n  \"args\": { \"max_age_hours\": 24 }\n}\n\n\n→ Retourne les sessions récupérables + purge automatique des sessions > 24h stale.\n\nPour monitorer :\n\n{\n  \"tool\": \"acp_session_list_active\",\n  \"args\": { \"include_stale\": false }\n}\n\nDécision d'architecture — ACP session store\nOption\tDécision\tRaison\nRedis\t❌ NON\tTrop lourd pour single-operator, dépendance externe\nSQLite\t❌ NON\tOverkill pour des clés simples, migration schema\nJSON file (atomic rename)\t✅ OUI\tZéro dépendance, atomic write (tmp + os.replace), léger\nAutonomous Session Bootstrap (H3)\n\nProblè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.\n\nSéquence obligatoire avant sessions_spawn\n\nÉtape 1 — Validation dry_run (vérifier les clés sans envoyer) :\n\n{\n  \"tool\": \"fleet_session_inject_env\",\n  \"args\": {\n    \"env_vars\": {\n      \"ANTHROPIC_API_KEY\": \"<your_key>\",\n      \"OPENCLAW_MODEL\": \"claude-3-5-sonnet-20241022\"\n    },\n    \"dry_run\": true\n  }\n}\n\n\n→ Vérifie que les clés passent l'allowlist. Si rejected non vide, les clés sont invalides.\n\nÉtape 2 — Injection effective avant spawn :\n\n{\n  \"tool\": \"fleet_session_inject_env\",\n  \"args\": {\n    \"env_vars\": {\n      \"ANTHROPIC_API_KEY\": \"<your_key>\",\n      \"OPENCLAW_MODEL\": \"claude-3-5-sonnet-20241022\"\n    },\n    \"filter_tags\": [\"engineering\", \"quality\"]\n  }\n}\n\n\nÉtape 3 — Spawn la session (via Gateway direct) :\n\n{\n  \"method\": \"sessions_spawn\",\n  \"params\": {\n    \"agent\": \"engineering\",\n    \"reply_session\": \"main\"\n  }\n}\n\nClés autorisées (allowlist intégrée)\nANTHROPIC_API_KEY | OPENAI_API_KEY | OPENROUTER_API_KEY | GEMINI_API_KEY\nOPENCLAW_MODEL | OPENCLAW_PROVIDER | OPENCLAW_MAX_TOKENS\nCLAW_MODEL | CLAW_PROVIDER | PROXY_URL | CUSTOM_*\n\n\nJamais dans les logs — les valeurs sont masquées avec ****{last4}.\n\nCron Outside Sandbox (H4)\n\nProblème : cron tools sont sur la denylist dans les sessions Docker sandbox. Tout workflow autonome planifié dans un container non-main est bloqué.\n\nSolution : Planifier sur la session main (accès hôte) via fleet_cron_schedule.\n\n{\n  \"tool\": \"fleet_cron_schedule\",\n  \"args\": {\n    \"command\": \"node scripts/daily-report.js\",\n    \"schedule\": \"0 9 * * 1-5\",\n    \"session\": \"main\",\n    \"description\": \"Daily business report — Monday to Friday 9h\"\n  }\n}\n\n\nUtiliser fleet_cron_schedule quand :\n\n✅ La tâche est un script léger et déterministe\n✅ La tâche ne nécessite pas d'isolation sécurité\n✅ La command passe l'allowlist [a-zA-Z0-9 /._-=]+\n\nUtiliser sessions_spawn (session non-main) quand :\n\n✅ La tâche implique du code non vérifié / externe\n✅ Isolation sécurité requise (sandbox Docker)\n✅ La tâche peut se déclencher ad-hoc (pas planifiée)\nWorkspace Locking (H5)\n\nProblème : Race condition documentée (#29947) sur shared-workspace read/modify/write. Plusieurs sessions agent peuvent corrompre la même ressource partagée.\n\nPattern acquire / work / release\n// 1. Acquérir le lock\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"acquire\",\n    \"owner\": \"engineering-session-001\",\n    \"timeout_s\": 30\n  }\n}\n\n// 2. Faire le travail (read → modify → write)\n// ... vos opérations sur la ressource ...\n\n// 3. Libérer le lock\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"release\",\n    \"owner\": \"engineering-session-001\"\n  }\n}\n\n\nVérifier le statut d'un lock :\n\n{\n  \"tool\": \"openclaw_workspace_lock\",\n  \"args\": {\n    \"path\": \"shared/config.json\",\n    \"action\": \"status\",\n    \"owner\": \"any\"\n  }\n}\n\nRègles\nLe lock est advisory (pas kernel-level) — tous les agents doivent coopérer\ntimeout_s max = 300s. Si lock non acquis → ok: false + current_owner\nToujours release dans un bloc try/finally pour éviter les locks orphelins\nUn lock expired ne se libère pas automatiquement — utiliser acp_session_restore pour purger les owners stale\nMonitoring de santé ACP\n\nFlux de monitoring recommandé (à exécuter périodiquement) :\n\nacp_session_list_active → sessions stale > 2h → acp_session_restore(max_age_hours=2) → recheck\n\n\nSi restored: 0 et purged > 0 après un intervalle normal → le bridge a crashé et les sessions ont été perdues → notifier via firm_export_slack_digest.\n\nOpenClaw gaps : C4 (ACP in-memory), H3 (#29886 isolated sessions no provider env), H4 (#29921 cron sandbox denylist), H5 (#29947 race condition)\n\n💎 Support\n\nSi ce skill vous est utile, vous pouvez soutenir le développement :\n\nDogecoin : DQBggqFNWsRNTPb6kkiwppnMo1Hm8edfWq"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/romainsantoli-web/firm-acp-bridge",
    "publisherUrl": "https://clawhub.ai/romainsantoli-web/firm-acp-bridge",
    "owner": "romainsantoli-web",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/firm-acp-bridge",
    "downloadUrl": "https://openagent3.xyz/downloads/firm-acp-bridge",
    "agentUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent",
    "manifestUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/firm-acp-bridge/agent.md"
  }
}