Session Bridge for Codex

Tus chats de Codex, disponibles en todos tus equipos.

Session Bridge sincroniza, respalda y restaura el historial local de Codex entre equipos Windows mediante un repositorio privado y dedicado de GitHub. No necesita un servidor propio ni una computadora permanentemente encendida, y nunca selecciona ni mezcla repositorios de proyectos.

Vista previa privada (0.1.0): esta versión se distribuye como VSIX para Windows x64. Antes de usarla con conversaciones importantes, conserva una copia de seguridad y completa la validación inicial en dos equipos.

Lo esencial

• Sincronización automática: detecta sesiones estables, consulta cambios remotos cada 30 segundos y continúa trabajando aunque VS Code esté cerrado.
• Historial completo: incorpora chats existentes durante la primera carga, no solamente las conversaciones nuevas.
• Restauración verificable: descarga todo a staging, valida SHA-256 y modifica Codex únicamente después de comprobar el conjunto completo.
• Chats grandes eficientes: divide los eventos en fragmentos Brotli inmutables de hasta 1 MiB y evita volver a subir contenido idéntico.
• Conflictos sin pérdida: si dos equipos continúan el mismo chat, conserva ambas ramas para que el usuario decida cuál mantener.
• Integración segura con Codex: usa operaciones oficiales del app-server y nunca escribe directamente las bases SQLite internas.
• GitHub privado: inicia sesión desde VS Code, acepta solo un repositorio privado dedicado y no solicita un PAT manual al usuario.
• Servicio en segundo plano: instala un auxiliar por usuario, sin permisos de administrador, con logs redactados y comunicación local autenticada.

Cómo funciona

1. La primera PC publica el historial. Session Bridge inventaría chats activos, archivados y sesiones internas; espera estabilidad, crea fragmentos verificables y completa la carga inicial.
2. Los demás equipos restauran una copia comprobada. Cada descarga se valida antes de tocar el historial local. Si ya existen chats, primero se crea un respaldo.
3. La sincronización continúa en ambos sentidos. El ciclo normal es pull → verificar → reconciliar → indexar → push. Las respuestas en progreso y líneas JSON incompletas nunca se publican.

Los cambios de nombre o archivado actualizan solo la metadata. Los fragmentos ya guardados permanecen inmutables y no se duplican.

Inicio rápido

1. Equipo principal

1. Desactiva Agent Sessions Sync para evitar una doble sincronización.

2. Instala el VSIX con Extensions: Install from VSIX... o desde PowerShell:

   code --install-extension session-bridge-for-codex-0.1.0.vsix
   

3. Ejecuta Session Bridge: Configurar.

4. Inicia sesión con GitHub desde el navegador.

5. Crea un repositorio privado nuevo o selecciona uno vacío y dedicado a Session Bridge.

6. Espera hasta que la carga inicial aparezca como verificada.

2. Equipo secundario

1. Instala exactamente el mismo VSIX y desactiva Agent Sessions Sync.
2. Inicia sesión con la misma cuenta autorizada.
3. Selecciona el mismo repositorio privado.
4. Si hay chats locales, usa Preparar este equipo como secundario para crear primero un respaldo.
5. Restaura el historial y comprueba IDs, nombres, cantidad de chats y visibilidad en Codex.

Comandos

Privacidad y seguridad

El contenido se almacena en el repositorio privado que el usuario elija. Session Bridge rechaza repositorios públicos y repositorios que contengan código u otros archivos ajenos al protocolo.

Esta versión no añade cifrado extremo a extremo: GitHub puede procesar el contenido almacenado aunque el repositorio sea privado. No uses un repositorio público ni uno compartido con personas que no deban acceder a las conversaciones.

Las credenciales no se guardan en settings.json, en los logs ni dentro del proyecto. En Windows se protegen mediante Credential Manager. Los logs son rotativos y redactados; no deben contener conversaciones ni tokens.

Requisitos y limitaciones

• Windows x64.
• VS Code 1.95 o posterior.
• Codex instalado y con un app-server compatible.
• Una cuenta de GitHub con permiso para crear o usar un repositorio privado dedicado.
• Agent Sessions Sync desactivada en todos los equipos.
• Git LFS y cifrado extremo a extremo no forman parte del MVP.
• Si una versión nueva de Codex cambia el protocolo, la importación se detiene y conserva staging, respaldo y contenido remoto para diagnóstico.

Arquitectura de la versión 0.1.0

• inventario de sesiones activas y archivadas de CODEX_HOME;
• clasificación de chats principales y sesiones internas/subagentes;
• nombres y metadata mediante Codex app-server;
• fragmentos JSONL Brotli inmutables con SHA-256;
• carga inicial completa, reanudable e idempotente;
• restauración transaccional en dos fases y rollback verificado;
• migración oficial de rollouts limitada a IDs concretos;
• detección de divergencias por revisión y SHA del manifiesto;
• named pipe autenticado y tarea programada por usuario;
• sondeo liviano por cabeza de rama antes de una sincronización completa;
• bloqueo automático cuando Agent Sessions Sync está activa.

Los datos propios de Session Bridge se guardan en %LOCALAPPDATA%\SessionBridge. La extensión no escribe directamente state_5.sqlite ni thread_history_1.sqlite.

Desarrollo y empaquetado

Requisitos de compilación: Windows x64, Node.js 20 o posterior, pnpm 10 o posterior y VS Code 1.95 o posterior.

pnpm install
pnpm run check
pnpm run lint
pnpm test
pnpm run test:service
pnpm run test:native
pnpm run test:appserver
pnpm run package

El empaquetador compila desde la copia maestra, crea staging local desechable con una lista permitida, ejecuta VSCE, valida el contenido, devuelve el VSIX y calcula su SHA-256. Si existe dist/session-bridge-service.exe, incluye el supervisor Rust; en desarrollo puede usarse el worker Node con las mismas funciones.

Consulta PROTOCOL.md, incluido en el proyecto, para el formato remoto, los estados del repositorio y las reglas de reconciliación.

Publicación posterior

Antes de publicar en Visual Studio Marketplace se configurarán el publicador definitivo, la GitHub OAuth App, el repositorio de código y la política de privacidad. La primera publicación pública deberá marcarse como pre-release hasta completar las pruebas reales en dos computadoras.

Licencia

MIT. Consulta el archivo LICENSE incluido con la extensión.