Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

36.4 KB
Raw Blame

Architecture de WebBrain

Version 25.7.12

Aperçu

WebBrain est une extension de navigateur qui donne à un LLM le contrÎle de l'onglet actif du navigateur de l'utilisateur. L'utilisateur tape une instruction en langage naturel dans un panneau latéral, et une boucle d'agent autonome appelle le LLM, exécute des appels d'outils (clic, saisie, navigation, lecture d'état de page, etc.), renvoie les résultats au LLM, et répÚte jusqu'à ce que la tùche soit terminée.

Il existe deux builds qui partagent presque tout le code :

  • Chrome — Manifest V3, service worker, Ă©vĂ©nements de confiance basĂ©s sur CDP
  • Firefox — Manifest V2, page d'arriĂšre-plan, Ă©vĂ©nements synthĂ©tiques uniquement

Ce document couvre l'architecture partagĂ©e et signale oĂč les builds divergent.


Architecture en couches

┌─────────────────────────────────────────────────────┐
│                 Panneau latĂ©ral (UI)                  │
│  sidepanel.js  ·  settings.js  ·  traces.js          │
│  locale: i18n.js / locales/*.js                      │
└──────────────┬──────────────────────────────────────┘
               │ chrome.runtime.sendMessage({action, ...})
               ▌
┌─────────────────────────────────────────────────────┐
│        Script d'arriùre-plan / Service Worker        │
│                                                      │
│  background.js        — routeur de messages          │
│    └─ agent.js        — boucle d'agent + executeTool()│
│         ├─ tools.js   — schĂ©mas d'outils + prompts   │
│         ├─ planner.js — Planificateur JSON Plan-before-Act│
│         ├─ adapters.js— conseils par site            │
│         ├─ permission-gate.js — octrois de capacitĂ©s │
│         ├─ credential-fields.js — dĂ©tection de secrets│
│         ├─ captcha-solver.js — intĂ©gration CapSolver │
│         ├─ loop-bucket.js — regroupement de boucles  │
│         └─ pdf-tools.js — extraction de texte PDF    │
│    ├─ providers/       — abstraction des fournisseurs│
│    ├─ network/         — fetch_url, tĂ©lĂ©chargements  │
│    ├─ trace/           — enregistreur IndexedDB opt. │
│    └─ recorder/        — orchestration d'enregistrement│
│                                                      │
│  Chrome uniquement :                                  │
│    ├─ cdp/             — Protocole DevTools Chrome   │
│    └─ offscreen/       — proxy fetch + enregistreur  │
└──────┬──────────────────────────────────────────────┘
       │ chrome.scripting.executeScript / CDP
       ▌
┌─────────────────────────────────────────────────────┐
│             Scripts de contenu (injectĂ©s)             │
│                                                      │
│  accessibility-tree.js  — constructeur arbre AX      │
│  content.js             — lecteur DOM, cliqueur,     │
│  agent-visual-indicator.js — effet de bordure + Stop │
└─────────────────────────────────────────────────────┘

Panneau latéral (src/ui/sidepanel.js)

L'interface de chat. Communique avec le script d'arriĂšre-plan via chrome.runtime.sendMessage (browser.runtime.sendMessage sur Firefox). Supporte trois modes de conversation :

  • Mode Ask — outils sĂ©mantiques/lecture seule uniquement (ASK_ONLY_TOOLS dans tools.js). L'agent peut lire, analyser et rĂ©sumer mais jamais cliquer, saisir ou naviguer. Ask exclut intentionnellement les outils de lecture dĂ©veloppeur/dĂ©bogage comme read_page_source, inspect_element_styles, et l'outil clarify ; la clarification ordinaire est juste une conversation normale.
  • Mode Act — les outils d'agent navigateur normaux du niveau de fournisseur sĂ©lectionnĂ©. L'agent peut entreprendre des actions rĂ©elles dans le navigateur.
  • Mode Dev — un mode d'action pour le dĂ©bogage de page et l'inspection HTML/CSS. Dev nĂ©cessite un niveau de fournisseur Mid ou Full, utilise le niveau de prompt Act sĂ©lectionnĂ©, puis ajoute l'annexe de prompt Dev et expose les modules complĂ©mentaires Dev tels que les outils source/style. Les fournisseurs de niveau Compact ne peuvent pas entrer en mode Dev.

Le niveau de modÚle est séparé du mode : compact | mid | full contrÎle combien d'outils normaux le modÚle voit, tandis que ask | act | dev contrÎle le type de tùche que l'utilisateur autorise.

L'utilisateur tape un message, le panneau envoie une requĂȘte dĂ©tachĂ©e {action: 'chat_start', text, mode, tabId, requestId}, puis se reconnecte au journal d'exĂ©cution possĂ©dĂ© par l'arriĂšre-plan pour recevoir les Ă©vĂ©nements agent_update. Fermer ou recharger le panneau ne transfĂšre pas la propriĂ©tĂ© de l'exĂ©cution et ne la redĂ©marre pas. Le panneau rend les appels d'outils, les rĂ©sultats, les cartes de rĂ©vision du plan, les invites de clarification et la rĂ©ponse finale de maniĂšre incrĂ©mentale.

Chaque paire question/réponse commence dans un état de défilement pensé pour la lecture : la question reste visible pendant qu'une longue réponse s'allonge. Une commande flottante alterne entre Suivre la réponse, Aller au plus récent et Retour à la question selon la position de lecture. Atteindre délibérément le bas réactive le suivi automatique ; les positions de lecture manuelles sont sinon préservées. Les cartes Plan/clarification/Continuer bloquantes, les invites de revue, les nouvelles questions et la sortie des commandes slash restent visibles lorsqu'elles nécessitent une action.

Script d'arriĂšre-plan (src/chrome/src/background.js)

Le routeur de messages central. Sur Chrome c'est un service worker (MV3) ; sur Firefox c'est une page d'arriÚre-plan persistante (MV2). Responsabilités :

  1. Router les messages entre le panneau latéral, les scripts de contenu et l'agent
  2. Gérer le cycle de vie de l'agent : chat / chat_stream / continue / abort / clear_conversation
  3. Gérer la configuration du fournisseur : charger, sauvegarder, tester, changer de fournisseur actif
  4. GĂ©rer la visibilitĂ© du panneau latĂ©ral : le groupe d'onglets « WebBrain » par fenĂȘtre contrĂŽle oĂč le panneau est activĂ©
  5. Observer les requĂȘtes XHR/fetch du mĂȘme onglet avec webRequest pour que la dĂ©tection de boucle puisse suggĂ©rer un raccourci fetch_url exact lorsque des clics d'interface rĂ©pĂ©tĂ©s dĂ©clenchent la mĂȘme requĂȘte d'arriĂšre-plan
  6. Exposer OAuth Claude, l'enregistrement d'onglet, CAPTCHA et autres sous-fonctionnalités comme gestionnaires de messages

Scripts de contenu (src/chrome/src/content/)

Injectés dans chaque page (<all_urls>). Deux fichiers chargés séquentiellement :

  1. accessibility-tree.js — expose window.__generateAccessibilityTree() (parcours DOM qui produit l'arbre textuel indentĂ© plat), window.__wb_ax_lookup() (rĂ©solveur ref_id → Element), et window.__wbElementMap (registre basĂ© sur WeakRef). LivrĂ© avant content.js pour que les gestionnaires AX soient prĂȘts.
  2. content.js — lecteur DOM, dĂ©couverte d'Ă©lĂ©ments interactifs, implĂ©mentations de clic/saisie/touches/dĂ©filement, et support iframe/frame. Gestionnaires pour tous les outils distribuĂ©s par script de contenu.

Flux complet d'un tour

L'utilisateur tape « créer un produit 'namaz' à 500 CNY, récurrent tous les 2 mois »

Étape 1 : Panneau latĂ©ral → ArriĂšre-plan

sidepanel.js → sendRunWithReconnect('chat_start', {
  text: 'create a product ...',
  mode: 'act',
  tabId: 42,
  requestId: '...'
})

Étape 2 : Arriùre-plan → Agent

background.js handleMessage('chat_start')
  → crĂ©e/persiste l'instantanĂ© runUi:<tabId>
  → lance le cycle de vie `chat` dĂ©tachĂ©
  → agent.processMessage(tabId, text, onUpdate, mode)

Étape 3 : Enrichir le premier message utilisateur

_enrichUserMessageWithCurrentPage(tabId, messages, userMessage)

  1. Collecter l'URL + le titre via chrome.tabs.get(tabId)
  2. Si /allow-api dĂ©fini pour cet onglet → injecter le prĂ©ambule [USER OVERRIDE]
  3. Si les adaptateurs de site sont activĂ©s → getActiveAdapter(url) → injecter les notes d'adaptateur
  4. Si le fournisseur supporte la vision (ou un modÚle de vision dédié configuré) :
     a. Capturer une capture d'Ă©cran de la fenĂȘtre via CDP
     b. (Optionnel) Sous-appeler le modÚle de vision dédié pour une description textuelle
     c. Attacher un bloc image_url ou une description de vision au premier message utilisateur
  5. Retourner le message utilisateur enrichi

Étape 4 : Porte Plan-before-Act

Les exécutions manuelles en mode action (Act ou Dev) appellent le fournisseur actif une fois avant la boucle d'outils avec le prompt JSON structuré de planner.js. Off utilise le schéma compact d'intention ; Essai et Strict utilisent le schéma de plan complet. Le stockage non défini utilise Essai par défaut, tandis qu'un Off explicite reste Off. Le planificateur voit la tùche utilisateur, l'URL/titre nettoyés, et un résumé d'historique récent court ; le contexte de la page est enveloppé comme donnée non fiable et les blocs d'image sont supprimés.

Si le planificateur retourne un JSON valide, le panneau latĂ©ral reçoit agent_update: plan_review et rend une carte de rĂ©vision modifiable. L'approbation Ă©pingle le plan approuvĂ© dans le bloc-notes pour qu'il survive Ă  la compaction du contexte. Le rejet, le dĂ©lai d'attente ou l'abandon par l'utilisateur arrĂȘte l'exĂ©cution avant que des outils navigateur soient exĂ©cutĂ©s. En mode Essai, un JSON toujours invalide aprĂšs une rĂ©paration fait passer uniquement ce tour au prompt Ask et aux outils en lecture seule ; le mode Strict s'arrĂȘte toujours avant les outils. Les exĂ©cutions planifiĂ©es peuvent dĂ©finir autoApprovePlanReview et Ă©pingler le plan sans afficher la carte.

Étape 5 : Boucle principale de l'agent

while (steps < maxSteps) {
  // 5a. Appeler le LLM
  const tier = provider.promptTier;
  const result = await provider.chat(messages, {
    tools: getToolsForMode(mode, { tier }),
    temperature: mode === 'ask' ? 0.3 : 0.15,
    maxTokens: 4096,
  })

  // 5b. Analyser la réponse
  if (result.toolCalls) {
    // 5c. Exécuter le lot d'outils
    for (const tc of result.toolCalls) {
      const toolResult = await executeTool(tabId, name, args)

      // 5d. Détection de boucle
      const loop = _checkLoop(tabId, name, args, toolResult)
      if (loop.kind === 'stop') → return loop.message

      // 5e. Capture d'écran automatique (si le mode le permet)
      if (_shouldAutoScreenshot(name)) {
        capturer capture CDP → attacher bloc image_url
      }

      messages.push({ role: 'tool', content: toolResult })
    }
  } else {
    // 5f. RĂ©ponse textuelle uniquement → rĂ©ponse finale
    return result.content
  }
}

Étape 6 : ExĂ©cution des outils

executeTool(tabId, name, args, onUpdate) distribue par nom :

Groupe d'outils Gestionnaire OĂč il s'exĂ©cute
get_accessibility_tree, click_ax, type_ax, set_field, hover message de script de contenu Contexte de page injecté
click, type_text, press_keys, scroll, read_page, etc. message de script de contenu Contexte de page injecté
navigate, go_back, go_forward API chrome.tabs / browser.tabs Script d'arriĂšre-plan
fetch_url, research_url, list_downloads, etc. network-tools.js Service worker
Outils de compétence activés Registre skills.js + executeHttpSkillTool() Service worker
done agent.js — capture une capture d'Ă©cran de vĂ©rification + sonde d'Ă©tat de page Service worker + CDP
clarify agent.js — pause pour saisie utilisateur Service worker
solve_captcha captcha-solver.js Service worker + API CapSolver
read_pdf pdf-tools.js Service worker
scratchpad_write agent.js — note Ă©pinglĂ©e en mĂ©moire Service worker
read_page_source, inspect_element_styles helpers agent/contenu Inspection source/style Dev uniquement
get_shadow_dom, shadow_dom_query, get_frames helpers contenu/CDP Replis avancés Full Act ; également ajoutés à Mid en mode Dev

Étape 6a : CompĂ©tences et exposition dynamique d'outils

ParamĂštres -> CompĂ©tences stocke les compĂ©tences activĂ©es dans customSkills (chrome.storage.local ou browser.storage.local). Au dĂ©marrage, background.js charge les compĂ©tences par dĂ©faut packagĂ©es depuis skills/*, initialise FreeSkillz.xyz la premiĂšre fois, et rafraĂźchit un enregistrement de compĂ©tence intĂ©grĂ©e existant lorsque la copie packagĂ©e change. Si l'utilisateur supprime une compĂ©tence par dĂ©faut, le marqueur d'initialisation empĂȘche qu'elle soit silencieusement rĂ©-ajoutĂ©e.

agent/skills.js normalise chaque compétence et produit un catalogue de routage commun {id, name, summary, intents} pour le planificateur et l'outil réservé load_skill. Le bloc optionnel webbrain-skill peut déclarer jusqu'à six identifiants d'intention uniques en minuscules (40 caractÚres maximum, format [a-z0-9][a-z0-9_-]*). Ces intentions sont des indices sémantiques indépendants de la langue, pas des mots-clés ni des sous-chaßnes obligatoires. Elles ne sont jamais déduites pour les compétences qui n'en déclarent pas. Un fichier Agent Skills SKILL.md importé peut fournir son name et sa description standard pour le nom et le résumé ; le nom saisi dans ParamÚtres et les métadonnées webbrain-skill restent prioritaires. Les métadonnées Agent Skills valides sont retirées avant le chargement du corps Markdown. Les manifestes webbrain-skill et webbrain-tools ne sont lus que dans ce corps, jamais dans les métadonnées Agent Skills.

Chaque exécution commence sans instructions complÚtes ni outils de compétence. Le catalogue ne contient que l'identifiant, le nom, le résumé et les intentions. Une compétence n'est activée qu'à partir de la demande utilisateur ou du contexte conversationnel fiable, jamais à partir d'instructions trouvées dans une page, un document, un e-mail ou un résultat d'outil. Ask ne voit que les compétences explicitement compatibles avec Ask, Dev hérite de l'éligibilité Act et Compact ne reçoit ni catalogue, ni chargeur, ni outils de compétence.

AprÚs activation, deux surfaces sont ajoutées uniquement pour l'exécution courante :

  • Instructions de prompt : buildCustomSkillsPrompt() supprime les blocs webbrain-tools dĂ©limitĂ©s avant d'ajouter le texte de la compĂ©tence au prompt systĂšme.
  • Exposition d'outils : buildSkillToolDefinitions() lit le manifeste et ajoute les schĂ©mas d'outils dĂ©clarĂ©s Ă  getToolsForMode(...) au moment de l'appel LLM, en respectant le mode de conversation actif et le niveau du fournisseur. Les outils de compĂ©tence de type tĂąche de tĂ©lĂ©chargement sont cachĂ©s en Ask et disponibles en modes action (Act et Dev) lorsque leur niveau dĂ©clarĂ© le permet.

Pour un tĂ©lĂ©chargement de mĂ©dia unique, le planificateur peut sĂ©lectionner FreeSkillz avant l'exĂ©cution. Si le modĂšle choisit quand mĂȘme download_social_media alors qu'une compĂ©tence inactive Ă©ligible possĂšde download_public_media, l'agent active cette compĂ©tence et renvoie une demande de nouvelle tentative vers l'outil spĂ©cialisĂ©. Sur un fil ou un profil, FreeSkillz doit d'abord inspecter la capture d'Ă©cran ou les liens visibles afin d'obtenir le permalien exact de la publication. Le repli navigateur n'est autorisĂ© qu'aprĂšs un vĂ©ritable Ă©chec de FreeSkillz ou si la compĂ©tence est indisponible. Le chemin agent refuse d'enregistrer des tampons MSE vidĂ©o/audio sĂ©parĂ©s ou non vĂ©rifiables et ne recommande ni ffmpeg ni connexion ; seuls les fichiers directs dĂ©jĂ  combinĂ©s restent un rĂ©sultat valide.

Le format du manifeste est un bloc JSON délimité dans le markdown de la compétence :

```webbrain-tools
{
  "tools": [
    {
      "name": "read_youtube_transcript",
      "kind": "http",
      "readOnly": true,
      "method": "POST",
      "endpoint": "https://freeskillz.xyz/v1/youtube/transcript",
      "activeTabUrlArg": "url",
      "inputUrlArg": "url",
      "resultPolicy": "untrusted",
      "parameters": {
        "type": "object",
        "properties": {
          "url": { "type": "string" }
        },
        "required": []
      }
    }
  ]
}
```

Les outils de compĂ©tence actuels supportent kind: "http" pour les intĂ©grations HTTPS GET/POST en lecture seule et kind: "httpDownloadJob" pour les tĂąches HTTPS POST de courte durĂ©e qui interrogent une URL de statut de mĂȘme origine, sauvegardent le fichier produit via les TĂ©lĂ©chargements du navigateur, et appellent le nettoyage ensuite. Les requĂȘtes utilisent credentials: "omit" et des listes d'autorisation optionnelles dans le manifeste peuvent restreindre les entrĂ©es de type URL. C'est intentionnellement un modĂšle de confiance Ă  l'importation pour le point d'accĂšs dĂ©clarĂ© ; les outils de tĂąche de tĂ©lĂ©chargement s'exĂ©cutent toujours en modes action et utilisent la porte d'autorisation normale des TĂ©lĂ©chargements avant de sauvegarder les fichiers. Les rĂ©sultats qui transportent du contenu tiers doivent dĂ©finir resultPolicy: "untrusted" afin que _wrapUntrusted() et _digestToolResult() les traitent comme des donnĂ©es plutĂŽt que des instructions.

Étape 7 : RĂ©sultats retournĂ©s Ă  l'interface

L'agent appelle onUpdate(type, data) pour chaque événement :

  • tool_call — nom de l'outil + arguments
  • tool_result — nom de l'outil + JSON du rĂ©sultat
  • text / text_delta — jetons de rĂ©ponse de l'assistant
  • warning — dĂ©tection de boucle, avertissements de navigation
  • clarify — question utilisateur en attente
  • plan_review — plan structurĂ© en attente d'approbation avant l'exĂ©cution des outils Act
  • error — erreurs d'exĂ©cution

L'arriÚre-plan relaie ces informations via chrome.runtime.sendMessage vers le panneau latéral, qui les rend de maniÚre incrémentale.


Sous-systÚmes clés

Planifier avant d'agir (planner.js)

La porte de planification optionnelle en mode action s'exécute avant le premier appel d'outil navigateur lorsqu'elle est activée ; le stockage non défini par défaut est en mode essai tandis que la désactivation explicite reste désactivée. Le prompt du planificateur nécessite un seul objet JSON avec un résumé, des étapes concrÚtes, une stratégie mémoire, une suggestion de planification, des risques, un mode d'action et skill_ids. Il ne reçoit que le catalogue des compétences éligibles. normalizePlan() limite et nettoie chaque champ et rejette les identifiants de compétence absents du catalogue ; les compétences validées ne sont activées qu'aprÚs l'approbation du plan et avant le premier appel du modÚle d'exécution. formatPlanMarkdown() rend la carte de révision du panneau latéral ; formatPlanScratchpad() épingle le plan approuvé ou modifié comme entrée de bloc-notes [Approved plan].

Les appels du planificateur sont tracĂ©s avec phase: "planner" lorsque l'enregistrement de trace est activĂ©. Ils utilisent Ă©galement la garde de limite de coĂ»t, les vĂ©rifications d'abandon, une nouvelle tentative de rĂ©paration JSON et la gestion no-think Qwen/DeepSeek. Un Ă©chec de rĂ©paration ne peut pas autoriser d'action : Essai passe Ă  un tour Ask en lecture seule, tandis que Strict s'arrĂȘte.

Chaque nouvel enregistrement de trace conserve webbrainVersion. /export inclut la version courante du manifeste ; /export --traces indique la version d'export et la version d'enregistrement de chaque tour, ou « indisponible » pour les traces héritées. L'export JSON de la page Traces ajoute exportedByWebBrainVersion tout en conservant le schéma rétrocompatible webbrain-trace/1.

Tùches planifiées (scheduler.js)

Le planificateur permet à l'agent de différer du travail vers une future session de navigateur en utilisant l'API alarms du navigateur. Il vit dans src/chrome/src/agent/scheduler.js (et son miroir Firefox) et est instancié comme ScheduledJobManager dans le script d'arriÚre-plan.

Types de tĂąche

Type Créé par Comportement
resume Outil schedule_resume Continue la conversation en cours dans le mĂȘme onglet Ă  un moment futur. Outil terminal — l'exĂ©cution en cours se termine quand il se dĂ©clenche.
task Outil schedule_task Exécute un prompt autonome rédigé par l'utilisateur à un moment futur, optionnellement récurrent.

Cycle de vie d'une tĂąche

pending → running → completed
       ↘ queued ↗ ↘ needs_user_input
                    ↓
               failed / cancelled / paused
  • pending — l'alarme est rĂ©glĂ©e ; en attente de dĂ©clenchement.
  • queued — l'alarme s'est dĂ©clenchĂ©e mais l'onglet Ă©tait occupĂ© ; rĂ©essaie toutes les 30 s (jusqu'Ă  120 reports avant Ă©chec).
  • running — l'agent exĂ©cute activement la tĂąche.
  • needs_user_input — l'agent a Ă©mis un clarify en cours d'exĂ©cution ; en attente de la rĂ©ponse de l'utilisateur.
  • paused — l'utilisateur ou les paramĂštres ont mis en pause la tĂąche, ou le planificateur a mis en pause une tĂąche rĂ©currente qui attend l'utilisateur ; aucune alarme n'est rĂ©glĂ©e.
  • cancelled / failed / completed — Ă©tats terminaux.

Cibles

  • current_tab — s'exĂ©cute sur l'onglet qui Ă©tait actif lors de la crĂ©ation de la tĂąche ; Ă©choue si l'onglet a disparu ou a naviguĂ© ailleurs.
  • url — ouvre (ou rĂ©utilise) un onglet pour une URL http(s) donnĂ©e au moment de l'exĂ©cution.

Planification

  • once — se dĂ©clenche Ă  un moment unique run_at ou after_seconds. after_seconds: 0 dĂ©marre la tĂąche immĂ©diatement.
  • recurring — se dĂ©clenche de maniĂšre rĂ©pĂ©tĂ©e Ă  interval_minutes (1 min – 1 an) ; aprĂšs chaque exĂ©cution, nextRunAt est avancĂ© et la prochaine alarme est rĂ©glĂ©e. Un intervalle fixe n'est pas un calendrier : 30 jours se dĂ©calent par rapport aux mois. Une exĂ©cution qui se termine par une question posĂ©e Ă  l'utilisateur par le planner (planner.js), ou un troisiĂšme Ă©chec sans exĂ©cution rĂ©ussie ou partielle entre-temps, met la tĂąche en pause (une exĂ©cution sans rĂ©sultat ne change pas le compte). La reprise d'une tĂąche mise en pause par le planificateur relance l'intervalle Ă  partir de ce moment ; une tĂąche mise en pause par l'utilisateur ou les paramĂštres garde sa prochaine exĂ©cution, ou s'exĂ©cute une minute aprĂšs la reprise si cette heure est passĂ©e. Dans les deux cas, le compte d'Ă©checs repart de zĂ©ro.

Une exĂ©cution planifiĂ©e, rĂ©currente ou ponctuelle, n'est jamais tenue d'appeler schedule_task, et l'Ă©tiquette de planification du planner ne la classe pas comme modifiant l'Ă©tat : son prompt enregistrĂ© garde le dĂ©lai d'origine de l'utilisateur (« dans 30 minutes, rappelle-moi
 »), et l'une ou l'autre exigence faisait replanifier la tĂąche Ă  chaque exĂ©cution ou l'empĂȘchait de rĂ©ussir. Le planner est informĂ© que l'exĂ©cution rĂ©alise une tĂąche existante, et une marque de modification d'Ă©tat que seule l'Ă©tiquette de planification explique est retirĂ©e (le plan brut doit ne dĂ©clarer que des outils d'observation pour chaque Ă©tape, fixer explicitement la soumission Ă  false et ne montrer ni tĂ©lĂ©chargement, ni tĂąche de site, ni destinataire de message, ni action de progression, ni compĂ©tence) ; les exigences propres du plan (modification d'Ă©tat, soumission, tĂ©lĂ©chargement) restent appliquĂ©es. Une exĂ©cution rĂ©currente reçoit la consigne de ne pas crĂ©er d'autre planification pour sa tĂąche ; une exĂ©cution ponctuelle, celle de ne pas replanifier la tĂąche et de ne crĂ©er une autre planification que si la tĂąche le demande explicitement (par exemple « lundi Ă  9 h, lancer une vĂ©rification toutes les heures »). La reprise planifiĂ©e d'une tĂąche interactive garde les deux exigences.

Persistance

Les tùches sont stockées dans chrome.storage.local sous la clé wb_scheduled_jobs comme un tableau JSON. Au redémarrage de l'arriÚre-plan, toutes les tùches en état running/needs_user_input sont rétrogradées à queued et réessayées, afin qu'aucune exécution ne soit silencieusement perdue.

ParamĂštres

Clé Défaut Effet
scheduledTasksEnabled true Si faux, les tĂąches en attente sont mises en pause au lieu d'ĂȘtre exĂ©cutĂ©es lorsque leur alarme se dĂ©clenche.
scheduledRequireConsequentialConfirmation true Passe un drapeau de politique à l'agent exigeant une confirmation explicite de l'utilisateur avant les actions planifiées conséquentes.

Outils LLM

Outil Quand l'utiliser
schedule_resume({after_seconds|run_at, reason, resume_instruction}) Pause durable pour la tĂąche en cours lorsqu'elle est bloquĂ©e par un Ă©vĂ©nement externe (build CI, email, dĂ©ploiement). Terminal — l'exĂ©cution se termine aprĂšs l'appel.
schedule_task({title, prompt, schedule, target, mode}) Créer une tùche autonome unique ou récurrente. after_seconds: 0 démarre maintenant ; les délais futurs non nuls nécessitent toujours au moins 60 secondes. Uniquement lorsque l'utilisateur demande explicitement du travail planifié.

Adaptateurs de site (adapters.js)

58+ adaptateurs injectent des conseils spécifiques au site dans le premier message utilisateur (et réinjectent lors de la navigation vers un site différent correspondant). Un SEUL adaptateur se déclenche à la fois (getActiveAdapter(url) retourne la premiÚre correspondance). Voir docs/site-adapters.md pour savoir comment en écrire un.

Arbre d'accessibilité (accessibility-tree.js)

Le principal chemin d'interaction avec la page. Produit un arbre textuel indentĂ© plat de la page oĂč chaque nƓud a un ref_id stable. Outils : get_accessibility_tree, click_ax, type_ax, set_field. Voir docs/accessibility-tree-and-refs.md.

Client CDP (cdp-client.js) — Chrome uniquement

Enveloppe l'API chrome.debugger pour :

  • ÉvĂ©nements de confiance — Input.dispatchMouseEvent, Input.dispatchKeyEvent (event.isTrusted === true)
  • Captures d'Ă©cran — Page.captureScreenshot de la surface de l'onglet telle qu'elle est Ă  l'Ă©cran, recadrĂ©e et mise Ă  l'Ă©chelle localement (un recadrage CDP redimensionnerait l'onglet visible pendant la capture) ; les tuiles pleine page gardent leur recadrage
  • RequĂȘtes DOM — Runtime.evaluate pour la percĂ©e du shadow DOM, DOM.getDocument pour les racines fermĂ©es

Sans CDP (Firefox), tous les événements sont synthétiques (el.click(), new KeyboardEvent()).

SystĂšme de fournisseurs (providers/)

Abstrait les backends LLM derriĂšre une interface commune (BaseLLMProvider) :

chat(messages, options)       → { content, toolCalls, usage }
chatStream(messages, options) → gĂ©nĂ©rateur asynchrone
supportsTools                 → boolĂ©en
supportsVision                → boolĂ©en
promptTier                    → 'compact' | 'mid' | 'full'
testConnection()              → { ok, error, model }

promptTier pilote Ă  la fois le prompt d'action et le sous-ensemble d'outils normaux. Les fournisseurs locaux par dĂ©faut sont Mid, les fournisseurs cloud sont forcĂ©s Full, et le drapeau legacy useCompactPrompt correspond Ă  Compact pour les configurations existantes. Le mode Dev est un mode de conversation sĂ©parĂ© : Mid/Full Dev utilise le niveau Act sĂ©lectionnĂ© plus SYSTEM_PROMPT_DEV_APPENDIX ; Compact Dev est bloquĂ© avant qu'une requĂȘte LLM soit envoyĂ©e.

Voir docs/providers-and-models.md.

Détection de boucle (agent.js)

Trois détecteurs indépendants s'exécutent aprÚs chaque appel d'outil :

  1. RĂ©pĂ©tition gĂ©nĂ©rale — les 6 derniers appels d'outils par (nom + hash des arguments + rĂ©sultat). Alerte Ă  3 identiques ou ABAB. ArrĂȘt Ă  8 alertes sans 2 appels sains entre les deux.
  2. Clic de coordonnĂ©es — regroupĂ© par 5px. Alerte Ă  5 clics dans le mĂȘme groupe. ArrĂȘt Ă  8.
  3. Navigation — URL instantanĂ© avant clic/navigation/iframe_click, comparer aprĂšs.

Lorsque l'observateur de mutation API optionnel est activĂ© et qu'une boucle click / click_ax rĂ©pĂ©tĂ©e est dĂ©tectĂ©e, _detectApiShortcut() vĂ©rifie le tampon webRequest par onglet alimentĂ© par background.js. L'observateur est dĂ©sactivĂ© par dĂ©faut. Si chaque clic rĂ©pĂ©tĂ© a produit la mĂȘme URL exacte + mĂ©thode HTTP dans une fenĂȘtre de 3 secondes, l'avertissement de boucle inclut une suggestion fetch_url({url, method}). Pour les mutations XHR/fetch rejouables, l'observateur conserve Ă©galement des corps de requĂȘte limitĂ©s et une petite liste d'autorisation d'en-tĂȘtes sĂ»rs pour le rejeu derriĂšre un replayRequestId opaque ; les jetons de formulaire cachĂ©s sont rĂ©utilisĂ©s en interne par fetch_url uniquement pour le mĂȘme onglet et la mĂȘme origine, non imprimĂ©s dans le contexte du modĂšle. Les mĂ©thodes d'Ă©criture nĂ©cessitent toujours l'Ă©tat /allow-api de la conversation ; les requĂȘtes GET et les capacitĂ©s non-rĂ©seau utilisent toujours la porte d'autorisation normale.

Gestion du contexte (agent.js)

  • Auto-compaction (_manageContext) — s'exĂ©cute Ă  la fois au dĂ©but de chaque tour utilisateur et en haut de chaque itĂ©ration de la boucle d'agent, afin qu'une longue exĂ©cution autonome se compacte en vol (« quand c'est dĂ» »), pas seulement entre les tours. Se dĂ©clenche selon la premiĂšre Ă©chĂ©ance parmi :
    • nombre de messages > 50, ou caractĂšres bruts > 80 000, ou
    • budget de jetons — le compteur de jetons d'entrĂ©e en cours dĂ©passant contextCompactRatio (0,75) de la fenĂȘtre de contexte du fournisseur actif (providers/base.js ; valeur par dĂ©faut de 16k pour les backends locaux et 128k pour cloud/routeur, catĂ©gorie-aware, surchargeable par fournisseur via config.contextWindow). Le compteur de jetons prĂ©fĂšre le usage.prompt_tokens rapportĂ© par le fournisseur (qui inclut le prompt systĂšme + les schĂ©mas d'outils) et se rabat sur une estimation de caractĂšres/4 sur le chemin de streaming.
    • Lors de la compaction, il conserve le prompt systĂšme + la tĂąche utilisateur originale + les anciens messages rĂ©sumĂ©s par LLM + les 30 derniers textuellement, puis Ă©met onUpdate('context_compacted', 
). Le panneau latĂ©ral rend un sĂ©parateur en ligne « Contexte automatiquement compactĂ© » pour que l'utilisateur sache que l'historique a Ă©tĂ© rĂ©sumĂ©, pas perdu.
  • DĂ©coupage d'urgence en cas de dĂ©passement de contexte : conserve seulement les 6 derniers messages (le repli dur lorsque le fournisseur rejette encore la demande aprĂšs l'auto-compaction)
  • Élagage d'images : supprime les images base64 de tous les messages sauf les 4 derniers avant chaque appel LLM
  • Limite de rĂ©sultat d'outil : rĂ©sultats individuels tronquĂ©s Ă  8 000 caractĂšres

Persistance des conversations et de l'interface

Les deux builds conservent un état isolé par onglet dans le stockage de session :

  • agentConv:<tabId> contient la conversation envoyĂ©e au fournisseur ;
  • tabChat:<tabId> reflĂšte le HTML du chat visible ;
  • runUi:<tabId> contient l'identitĂ© et l'Ă©tat de l'exĂ©cution dĂ©tachĂ©e, une fenĂȘtre bornĂ©e d'Ă©vĂ©nements, l'Ă©tat Plan/outils, le contenu terminal et le texte streamĂ© accumulĂ©.

Les Ă©critures de text_delta sont regroupĂ©es sur une fenĂȘtre glissante de 200 ms ; les Ă©vĂ©nements non-delta, les Ă©tats terminaux et les points de durabilitĂ© avant outil sont persistĂ©s immĂ©diatement. Le texte streamĂ© possĂšde sa propre limite, distincte de la fenĂȘtre de 256 Ă©vĂ©nements, afin qu'un panneau rouvert reconstruise correctement le Markdown en cours. Chrome utilise chrome.storage.session et Firefox browser.storage.session.


Différences clés entre Chrome et Firefox

Domaine Chrome (MV3) Firefox (MV2)
ArriÚre-plan Service worker (éphémÚre) Page d'arriÚre-plan (persistante)
ÉvĂ©nements CDP de confiance (isTrusted=true) SynthĂ©tiques (isTrusted=false)
Captures d'écran CDP Page.captureScreenshot avec émulation de focus limitée à l'exécution en arriÚre-plan browser.tabs.captureTab() pour capturer directement un onglet inactif
Persistance conversation/interface chrome.storage.session browser.storage.session
Document hors-écran Oui (proxy fetch + enregistreur) Non disponible
Enregistreur de trace IndexedDB (optionnel) IndexedDB (optionnel) — mĂȘme trace/recorder.js
Garde de soumission en double Oui Non disponible
execute_js Mode Dev via CDP Runtime.evaluate Mode Dev via l'évaluateur du script de contenu MV2
Percée Shadow DOM CDP pour racines fermées ; shadow_dom_query est Chrome uniquement Racines ouvertes uniquement
CORS localhost Repli proxy hors-Ă©cran Le serveur doit dĂ©finir les en-tĂȘtes CORS
Observateur de raccourci API Tampon URL/méthode chrome.webRequest Tampon URL/méthode browser.webRequest
Enregistrement d'onglet/écran par barre oblique chrome.tabCapture / getDisplayMedia() + hors-écran Non disponible
Panneau latéral API sidePanel (MV3) sidebar_action (MV2)
Téléversement de fichier Chemin CDP ou downloadId Rechargement via downloadId ou sélecteur de fichier WebBrain ; pas de chemin local arbitraire

Tout le reste (boucle d'agent, outils, adaptateurs, fournisseurs, détection de boucle, gestion de contexte, prompts systÚme) est architecturalement identique entre les deux builds.


Structure des répertoires

src/
├── chrome/           # Build Chromium (MV3)
│   ├── manifest.json
│   ├── skills/       # CompĂ©tences par dĂ©faut packagĂ©es
│   └── src/
│       ├── agent/    # agent.js, tools.js, skills.js, adapters.js, scheduler.js, ...
│       ├── cdp/      # Client CDP (Chrome uniquement)
│       ├── content/  # accessibility-tree.js, content.js, ...
│       ├── network/  # network-tools.js
│       ├── offscreen/# Proxy fetch + enregistreur par barre oblique (Chrome uniquement)
│       ├── providers/# BaseLLMProvider + implĂ©mentations
│       ├── recorder/ # Orchestration d'enregistrement
│       ├── trace/    # Enregistreur IndexedDB
│       └── ui/       # sidepanel, settings, traces, i18n
├── firefox/          # Build Firefox (MV2)
│   ├── manifest.json
│   ├── skills/       # CompĂ©tences par dĂ©faut packagĂ©es
│   └── src/          # MĂȘme structure, moins cdp/, offscreen/, recorder/
└── vendor/           # Bibliothùques tierces (pdfjs, katex)

Les deux builds partagent le mĂȘme ensemble d'adaptateurs, implĂ©mentations de fournisseurs, arbre d'accessibilitĂ© et la plupart du code d'outils. Le motif src/shared/ est intentionnellement Ă©vitĂ© — les fichiers sont dupliquĂ©s entre chrome/ et firefox/ afin que chaque build soit autonome et puisse ĂȘtre chargĂ©e directement sans Ă©tape de build pour le dĂ©veloppement.


ModÚle de sécurité

Voir docs/security-model.md et src/chrome/ARCHITECTURE.md pour les détails.

Points clés :

  • L'extension s'exĂ©cute avec les permissions <all_urls> + debugger — accĂšs complet au navigateur
  • Pas d'authentification supplĂ©mentaire : l'agent EST la session navigateur de l'utilisateur
  • Ask est en lecture seule ; Act et Dev sont des modes d'action. Dev ajoute des outils source/style/dĂ©bogage de page et est bloquĂ© pour les fournisseurs de niveau Compact.
  • Planifier avant d'agir peut nĂ©cessiter une approbation humaine avant tout appel d'outil en mode action
  • Le drapeau /allow-api limite les mĂ©thodes HTTP destructrices via fetch_url
  • Les rĂ©sultats d'outils sont limitĂ©s Ă  8 Ko pour rĂ©duire la surface d'injection de prompt
  • strictSecretMode empĂȘche le modĂšle de citer des identifiants dans les rĂ©sumĂ©s
  • Les donnĂ©es de trace sont locales uniquement (IndexedDB), jamais transmises
  • Le proxy hors-Ă©cran ne transmet que le trafic SDK du fournisseur
  • Les adaptateurs financiers injectent des conseils de confirmation supplĂ©mentaires