Open-source AI browser agent for Chrome and Firefox (monorepo) đ§
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_TOOLSdanstools.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 commeread_page_source,inspect_element_styles, et l'outilclarify; 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 :
- Router les messages entre le panneau latéral, les scripts de contenu et l'agent
- Gérer le cycle de vie de l'agent :
chat/chat_stream/continue/abort/clear_conversation - Gérer la configuration du fournisseur : charger, sauvegarder, tester, changer de fournisseur actif
- GĂ©rer la visibilitĂ© du panneau latĂ©ral : le groupe d'onglets « WebBrain » par fenĂȘtre contrĂŽle oĂč le panneau est activĂ©
- Observer les requĂȘtes XHR/fetch du mĂȘme onglet avec
webRequestpour que la dĂ©tection de boucle puisse suggĂ©rer un raccourcifetch_urlexact lorsque des clics d'interface rĂ©pĂ©tĂ©s dĂ©clenchent la mĂȘme requĂȘte d'arriĂšre-plan - 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 :
accessibility-tree.jsâ exposewindow.__generateAccessibilityTree()(parcours DOM qui produit l'arbre textuel indentĂ© plat),window.__wb_ax_lookup()(rĂ©solveur ref_id â Element), etwindow.__wbElementMap(registre basĂ© sur WeakRef). LivrĂ© avantcontent.jspour que les gestionnaires AX soient prĂȘts.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 blocswebbrain-toolsdé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 + argumentstool_resultâ nom de l'outil + JSON du rĂ©sultattext/text_deltaâ jetons de rĂ©ponse de l'assistantwarningâ dĂ©tection de boucle, avertissements de navigationclarifyâ question utilisateur en attenteplan_reviewâ plan structurĂ© en attente d'approbation avant l'exĂ©cution des outils Acterrorâ 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 unclarifyen 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 uniquerun_atouafter_seconds.after_seconds: 0dĂ©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,nextRunAtest 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.captureScreenshotde 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.evaluatepour la percée du shadow DOM,DOM.getDocumentpour 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 :
- 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.
- Clic de coordonnĂ©es â regroupĂ© par 5px. Alerte Ă 5 clics dans le mĂȘme groupe. ArrĂȘt Ă 8.
- 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 viaconfig.contextWindow). Le compteur de jetons prĂ©fĂšre leusage.prompt_tokensrapportĂ© 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-apilimite les méthodes HTTP destructrices viafetch_url - Les résultats d'outils sont limités à 8 Ko pour réduire la surface d'injection de prompt
strictSecretModeempĂȘ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