LLM Wiki for Chrome

Sustrato de ejecución público y sin contenido para adaptadores llm-wiki específicos. Proporciona una extensión de Chrome, un host de Mensajería Nativa incluido en la lista blanca, un relé de socket Unix privado y un contrato de trabajo tipado versionado.

El código fuente de la extensión y del conector local es público. Las concesiones del navegador, los datos de las páginas, las credenciales, las ranuras de resultados privados y los sockets en tiempo de ejecución permanecen locales y nunca son contenido del repositorio. La disponibilidad del código fuente público no es un lanzamiento en Chrome Web Store ni un permiso para publicar datos de usuario.

Esto no es un agente de navegador autónomo en lenguaje natural. Expone una pequeña superficie de herramientas de agente estructurada—pestañas compartidas, instantánea de accesibilidad, captura de pantalla del viewport, clic semántico, inserción de texto privado, combinación de teclas y desplazamiento—y compila cada llamada en el mismo protocolo tipado de destino exacto. No acepta JavaScript arbitrario, métodos CDP sin procesar, código descargado, acceso ambiental al navegador o acciones creadas por la página. Los adaptadores específicos del proveedor aún poseen un enrutamiento más sólido, autenticación, registros, recuperación, idempotencia y verificación final de lectura inversa para flujos de trabajo consecuentes.

Guía de instalación, colaboración, seguridad y solución de problemas →

Flujo de clic para colaborar

La extensión no necesita acceso persistente al sitio ni registro de host de Chrome por página. El usuario abre una página HTTPS y hace clic en la acción de la extensión. Su nombre visible en Chrome es LLM Wiki for Chrome; la terminología de ejecutor de navegador se mantiene solo para el protocolo interno y la implementación.

Ese gesto de usuario en Chrome crea una nueva concesión de colaboración efímera vinculada a la pestaña, URL y origen exactos. Al hacer clic en pestañas adicionales se construye un espacio de trabajo explícito de hasta 16 concesiones; el ejecutor nunca enumera pestañas no relacionadas. La navegación del mismo origen rota el ID de concesión y la URL exactos, por lo que los programas obsoletos fallan de forma segura. Una concesión se revoca cuando la pestaña sale de su origen, se cierra, o el usuario detiene esa pestaña o todo el espacio de trabajo en el panel lateral.

Una concesión activa es visible en la página como un contorno verde fijo y una píldora LLM WIKI • CONTROLLED, además de una insignia de acción ON. El marcador está empaquetado, no es interactivo, es ciego al contenido y se inyecta solo después del clic en la extensión; se elimina cuando la concesión se revoca y nunca recibe contenido de la página o del trabajo.

El oyente de acciones recibe la concesión activeTab de Chrome y abre sincrónicamente el panel lateral para esa pestaña exacta. La carga del panel confirma la concesión creada por la acción; un mensaje de panel retransmitido nunca intenta abrir el panel ni fabricar un gesto de usuario. Su botón de conexión es un control de estado/reintento, no un sustituto del gesto de la barra de herramientas que crea la autoridad activeTab. El estado conectado significa que la concesión se ha publicado a través del conector local activo, por lo que el agente puede detectar la preparación con browser_status sin pedir al usuario que inspeccione los internos de la extensión.

El agente local y los adaptadores específicos recuperan el espacio de trabajo privado a través del socket nativo. Un agente directo debe primero listar las concesiones exactas cliqueadas y nombrar un ID de colaboración en cada llamada de herramienta. El servidor entonces compila un programa tipado fijo y falla de forma segura si la concesión o la página han cambiado. El clic autoriza lecturas limitadas e interacción estructurada en esa pestaña exacta; nunca concede acceso ambiental al navegador. Los flujos de trabajo de proveedores consecuentes aún usan un adaptador específico para precondiciones más sólidas y verificación independiente.

El código del adaptador aún debe instalarse y ser confiado una vez. La concesión de colaboración reemplaza el registro por recurso y el OAuth del proveedor solo para flujos de trabajo que pueden inspeccionar y verificar a través de la interfaz de usuario del navegador. Un adaptador específico puede mantener una API de primera parte como una ruta de verificación más sólida opcional.

Los programas de mutación pueden vincular una huella de revisión propiedad del proveedor con assert_ax_private_sha256. El ejecutor recalcula la proyección de accesibilidad limitada en la pestaña expuesta exacta inmediatamente antes del límite de mutación gobernada y falla de forma segura si hay desviación. El hash esperado sigue siendo un valor privado; ni él ni el contenido proyectado de la página se muestran en el panel lateral.

Los adaptadores de proveedores usan el cliente incluido directamente:

from browser_executor.client import BrowserExecutorClient

executor = BrowserExecutorClient()
collaboration = executor.collaboration_for_url(expected_url)
if collaboration is None:
    raise RuntimeError("click the extension on the target page")

# Bind collaboration_id, url, and origin into the signed typed program.
result = executor.run(program, private_values=private_values)

Codex y otros clientes MCP usan la superficie de colaboración directa neutral al proveedor en lugar de construir programas ellos mismos:

.venv/bin/python adapter.py mcp-server

El servidor MCP publica un inventario fijo de herramientas estructuradas que cubre ciclo de vida explícito de pestañas, navegación exacta del mismo origen, esperas, instantáneas de accesibilidad, capturas de pantalla de viewport/región/página completa, geometría de elementos, clic/pasar/teclear/seleccionar/arrastrar/tecla/desplazamiento, diagnósticos limitados, transferencia de archivos de raíz registrada, activación de la interfaz de usuario del administrador de contraseñas y borrador de flujo de trabajo en memoria. No tiene programa arbitrario, selector CSS, script, herramienta de ejecución en lenguaje natural ni consulta de pestañas no relacionadas. El contenido de la página se devuelve solo al agente local solicitante para la solicitud activa y no es persistido por este repositorio ni se muestra en el panel lateral.

Related MCP server: browser-mcp

Estado de desarrollo

La rama de desarrollo actual extiende la base 0.0.1 con el primer segmento de ejecución limitado:

• hash estricto y validación de programas;

• pruebas de decisión de políticas multilingüe para el cliente Python y el validador MV3;

• declaraciones exactas de destino HTTPS y acciones limitadas;

• concesiones de pestaña activa creadas por clic sin permisos de host persistentes;

• un espacio de trabajo de colaboración de múltiples pestañas limitado con búsqueda privada de URL exacta;

• sockets nativos por instancia de Chrome agregados por el cliente local, de modo que varios perfiles o procesos de Chrome no puedan sobrescribir las pestañas compartidas de otros;

• un contorno/píldora de página fijo y una insignia de barra de herramientas que muestra exactamente qué pestañas están controladas;

• un grupo de pestañas verde LLM Wiki que contiene solo concesiones explícitas;

• primitivas de abrir/navegar/historial/recargar del mismo origen, enfoque/cierre de pestaña exacta, esperas semánticas, pasar por encima, selección de opciones, arrastrar/soltar y desplazarse a un elemento;

• colección de accesibilidad aplanada y limitada a través de destinos de marcos secundarios adjuntos, con geometría e interacciones vinculadas a la sesión; el descubrimiento semántico de AX también cubre árboles shadow abiertos sin habilitar el recorrido arbitrario del DOM;

• capturas de pantalla de página completa con límite de región y dimensiones, geometría de elementos semánticos y métricas de rendimiento limitadas;

• raíces de carga/descarga locales a la máquina con comprobaciones de realpath, verificación de descarga completada, aplicación de estado de peligro, hashes de transmisión y sin autoridad implícita del sistema de archivos;

• modos de autorización limitada manual, de plan aprobado y automático con acciones protegidas que siempre recurren a la confirmación local y un contador de decisiones de sesión sin contenido;

• notificaciones de finalización/atención sin contenido;

• programaciones de instantáneas de solo lectura en memoria cancelables cuyos resultados privados se recuperan una vez y cuya autoridad expira con el proceso MCP o la concesión de pestaña;

• grabación en memoria de acciones de agente ya escritas en un borrador controlador de proveedor ligado a hash, que requiere revisión y deliberadamente no reproducible;

• activación de la interfaz de usuario del administrador de contraseñas que nunca recibe un valor de credencial; y

• un SDK de controlador de proveedor que vincula adaptadores específicos a la concesión exacta, hash de plan aprobado, un callback de mutación y verificación de poscondición propiedad del adaptador;

• concesión de pestaña de oyente de acciones, control de estado/reintento del panel lateral y herramienta de preparación de agente sin contenido;

• un espacio de trabajo de panel lateral sin contenido, medidor de progreso, revocación por pestaña y cancelación;

• capacidades separadas de lectura y mutación;

• un callback de mutación gobernada en el cliente Python;

• identidad de extensión estable y origen exacto del host nativo;

• estado local privado, rutas de socket cortas, límites de mensajes y un trabajo activo;

• activación de pestaña exacta y navegación del mismo origen revisada;

• una superficie de agente MCP local directa que hace que un clic en la extensión sea inmediatamente detectable y controlable por el agente sin una concesión OAuth del proveedor;

• lecturas, esperas y extracción privada de DOM y árbol de accesibilidad permitidos;

• captura JPEG privada del viewport con límite de bytes y sin persistencia en el lado del ejecutor;

• desplazamiento de viewport limitado, colección de listas largas deduplicando y extracción privada de enlaces/descripciones de AX;

• captura de registro de navegador de pestaña exacta limitada a través de ranuras de resultados privadas;

• captura de metadatos de solicitud de pestaña exacta limitada que elimina cadenas de consulta e ignora encabezados, cuerpos, cookies, iniciadores y detalles de seguridad;

• captura de API de consola de pestaña exacta limitada que retiene solo argumentos escalares y nunca evalúa ni desreferencia objetos remotos;

• acciones tipadas de clic, enfoque, combinación de teclas e inserción de texto privado;

• cancelación, detección de desviación de enfoque objetivo, límites de tamaño de resultado y limpieza del depurador en la medida de lo posible (la cancelación se detiene en la siguiente acción limitada y no puede revertir una mutación que ya comenzó);

• autorización de pre-mutación única antes de un efecto de proveedor; y

• un manifiesto de autoprueba llm-wiki sin ruta; y

• un panel de estado de extensión sin contenido con estados conectado, ejecutándose, autorización y fallo.

Esta rama no es un lanzamiento ni un reemplazo de proveedor instalado. Las ejecuciones en paralelo de adaptadores específicos, la verificación propiedad del proveedor, las pruebas de actualización/reversión y la aprobación explícita del lanzamiento siguen siendo necesarias antes de un 0.1.0 consolidado.

Límite del repositorio

Material permitido para seguimiento:

• código ejecutable y activos de extensión;

• esquemas de protocolo y documentación de seguridad; y

• fixtures sintéticos y pruebas deterministas.

Nunca confirmar URLs o identificadores de recursos reales, texto de páginas, capturas de pantalla, capturas, planes, recibos, resultados extraídos, cookies, credenciales, almacenamiento del navegador o corpus de proveedores. Las entradas y salidas en tiempo de ejecución permanecen en el plano de datos controlado por separado del adaptador específico y deben permanecer en memoria siempre que sea posible.

Arquitectura

local agent through fixed MCP tools OR a targeted provider adapter
  -> select one exact user-created click grant from the private collaboration workspace
  -> deterministic typed program + exact approved plan hash
  -> BrowserExecutorClient over a private Unix socket
  -> allowlisted Native Messaging host
  -> shared MV3 extension on the exact user-exposed tab
  -> one-shot before-mutation challenge when required
  -> private result slots returned only to the targeted adapter

llm-wiki puede ver el manifiesto del adaptador self-test sin ruta de este repositorio, pero nunca enruta una solicitud externa de edición o investigación directamente al ejecutor.

Empaquetado e instalación

El producto instalable se divide en el límite de seguridad de Chrome:

• llm-wiki-chrome compañero nativo: el cliente Python, servidor MCP fijo, host de Mensajería Nativa, instalador, diagnósticos y activos de extensión empaquetados;

• LLM Wiki for Chrome: el ZIP de la extensión MV3 de código fuente público. La publicación en Chrome Web Store sigue siendo un paso de lanzamiento separado que requiere aprobación explícita; cargar la ruta desempaquetada sigue siendo el flujo de trabajo de desarrollo.

La fórmula Homebrew solo para desarrollo está disponible desde nvk/tap como una compilación HEAD. Deliberadamente no es un lanzamiento estable:

brew install --HEAD nvk/tap/llm-wiki-chrome
llm-wiki-chrome install
llm-wiki-chrome doctor

install escribe el registro de Mensajería Nativa de origen exacto. No instala un demonio: Chrome inicia el host bajo demanda y se comunica con él a través de la entrada/salida estándar. Cada host de Chrome crea un socket privado por proceso en el directorio de tiempo de ejecución determinista /tmp/llm-wiki-chrome-<uid>/. La CLI, el servidor MCP y los adaptadores específicos descubren esos sockets automáticamente. No hay argumento de socket normal, puerto, código de emparejamiento o variable de entorno. La anulación de entorno existente permanece solo para configuraciones excepcionales de espacio aislado o desarrollo.

Para una instalación de desarrollo desempaquetada, pregunta al paquete por la ruta exacta:

llm-wiki-chrome extension-path

Carga ese directorio desde chrome://extensions y ejecuta llm-wiki-chrome doctor. healthy: true confirma el paquete y el registro de Mensajería Nativa; connected: true aparece mientras Chrome tiene abierto el puerto nativo de la extensión. Desinstala solo el registro del compañero nativo con:

llm-wiki-chrome uninstall

La transferencia de archivos está deshabilitada por defecto. Habilita solo raíces locales explícitas de la máquina en ~/.config/llm-wiki/browser-executor.json:

{
  "upload_roots": ["/absolute/private/staging/uploads"],
  "download_roots": ["/absolute/private/staging/downloads"]
}

Cada ruta rechaza un enlace simbólico final, resuelve su cadena principal y debe permanecer dentro de una raíz registrada. Los valores de carga viajan solo en ranuras privadas. Las descargas deben estar completas, aceptadas como seguras por Chrome, dentro de una raíz registrada, y son hasheadas por el compañero local antes de ser devueltas al llamante.

El panel lateral ofrece Manual, Approved plan y Automatic bounded jobs. El valor predeterminado es Approved plan. La carga de archivos, el manejo de diálogos y la activación del bróker de credenciales siguen siendo acciones protegidas y siempre requieren confirmación manual local. El historial de autorización es un contador de sesión sin contenido, no un registro de contenido de página.

La grabación del flujo de trabajo captura solo las operaciones ya solicitadas a través de la superficie fija de MCP. browser_record_stop devuelve un borrador en memoria, vinculado por hash, que requiere revisión. El ejecutor genérico nunca lo reproduce; un adaptador específico debe revisar, compilar, autorizar, registrar y verificar de forma independiente un flujo de trabajo de proveedor versionado. La superficie directa solo permite la programación limitada en memoria de una instantánea de solo lectura mientras la concesión exacta y el proceso de MCP permanecen activos. La programación duradera o recurrente, las mutaciones, la recuperación y los registros permanecen en el adaptador específico o en el programador externo, nunca en la capa de intención de la extensión.

Los adaptadores específicos pueden centralizar el límite de ejecución con browser_executor.driver.ProviderDriverSession, que rechaza la desviación del hash del plan o de la concesión exacta y requiere una poscondición status: verified propiedad del adaptador.

Construir un ZIP determinista y sin contenido para Chrome Web Store sin publicarlo:

python3 scripts/package_extension.py

Ninguna versión, etiqueta, carga en la tienda o actualización instalada se realiza mediante estos comandos de compilación.

Desarrollo

python3 -m venv .venv
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q adapter.py browser_executor tests
node --check extension/service-worker.js
node --check extension/protocol.mjs
node --check extension/executor.mjs
node --check extension/sidepanel.js

El conjunto determinista se complementa con una prueba de humo aislada en un navegador real. Requiere un par coincidente de Chrome for Testing y ChromeDriver, y un destino de lectura aprobado exacto proporcionado en tiempo de ejecución; no toca el perfil normal de Chrome ni imprime, persiste o devuelve el viewport capturado:

LLM_WIKI_BROWSER_E2E_TARGET_URL='<exact approved HTTPS target>' \
  .venv/bin/python tests/chrome/run_extension_e2e.py \
    --chrome '/path/to/Google Chrome for Testing' \
    --chromedriver '/path/to/chromedriver'

El arnés copia la extensión desempaquetada en un directorio temporal, añade una página de extensión solo para pruebas, ejecuta el programa de lectura firmado en Chrome sin cabeza y devuelve solo contadores sin contenido. Los binarios de Chrome no se descargan ni instalan mediante el repositorio.

La autoprueba no tiene contenido:

.venv/bin/python adapter.py describe
.venv/bin/python adapter.py execute --request /private/request.json \
  --response /private/response.json

Instalar el host nativo de la copia de origen una vez y registrar su comando de MCP:

.venv/bin/python adapter.py install

codex mcp add llm-wiki-browser \
  -- .venv/bin/python adapter.py mcp-server

Reiniciar una sesión de agente después del registro hace que el inventario de herramientas fijo esté disponible. Chrome aún no expone nada hasta que el usuario hace clic en la extensión en una pestaña HTTPS específica, y detener la colaboración revoca la concesión. Un tiempo de ejecución excepcional que no pueda acceder al directorio privado predeterminado /tmp puede configurar LLM_WIKI_BROWSER_EXECUTOR_NATIVE_SOCKET de manera consistente para ambos comandos, pero eso no forma parte del flujo de usuario empaquetado.

browser-install escribe un manifiesto de Mensajería Nativa y un lanzador de origen exacto. Úselo solo durante una tarea explícita de instalación o migración. Cargar la extensión desempaquetada, cambiar un perfil normal de Chrome y actualizar una copia instalada no forman parte del conjunto de pruebas y requieren una dirección explícita del usuario.

Modelo de seguridad

El ejecutor valida un hash de programa canónico, hash de plan, ID de colaboración activa, identidad/versión fija del controlador, destino exacto, capacidad, límites, vocabulario de acciones, slots privados y lista blanca de resultados de forma independiente en Python y la extensión. No hay permisos de host persistentes, acceso a <all_urls> ni scripts de contenido; la concesión activeTab de Chrome se crea solo mediante el clic del usuario en la extensión. El intérprete tiene una lista blanca de métodos CDP fija y no acepta Runtime.evaluate, métodos sin procesar, scripts o acciones generadas por la página.

La lista blanca fija de CDP también incluye ventanas emparejadas Log.enable/Log.disable y Network.enable/Network.disable. Esta última retiene solo escalares limitados privados: método de solicitud, origen/ruta, tipo de recurso, estado, MIME, caché y fallos; elimina cadenas de consulta y nunca retiene encabezados, cuerpos, cookies, iniciadores, detalles de seguridad ni IDs de solicitud. Ninguna capacidad expone métodos de diagnóstico sin procesar ni interceptación de solicitudes. Una ventana emparejada separada Runtime.enable/Runtime.disable retiene solo escalares limitados privados: tipos de Runtime.consoleAPICalled, marcas de tiempo y argumentos escalares. Ignora contextos, pilas, descripciones, vistas previas e IDs de objeto, y nunca permite evaluación, compilación, llamadas a funciones, ejecución de scripts ni acceso a propiedades. Cada proceso de host nativo de Chrome enlaza un socket privado único por debajo de la ruta base configurada. El cliente descubre solo aquellos sockets estrictamente nombrados, agrega sus espacios de trabajo de colaboración explícitos y enruta un trabajo al único host que posee su concesión exacta. Esto evita que múltiples perfiles de Chrome reemplacen el relé entre sí mientras se preserva una pestaña exacta por trabajo.

El ejecutor es código local de confianza, no una caja de arena del sistema operativo. Los adaptadores específicos siguen siendo responsables de autorizar cada efecto consecuente del proveedor y de probar el estado final del proveedor de forma independiente. Las herramientas de mutación directa cruzan un límite interno de un solo uso, pero deliberadamente no reclaman garantías transaccionales del proveedor. Consulte SECURITY.md.