@iaforged/context-code 1.0.84 → 1.0.86

package/docs/BRIDGES.md

@@ -0,0 +1,90 @@
+## Puentes con mensajería móvil
+
+Context Code puede conectarse con **Telegram** y **WhatsApp** para que veas y respondas la conversación completa desde tu móvil. Cada mensaje que escribes en la terminal se refleja en el chat, cada respuesta del modelo llega de vuelta, y cada herramienta que ejecuta el asistente (Bash, Read, Edit…) se resume en una línea. También puedes escribir **desde el móvil** y el texto se inyecta al REPL como si lo hubieras tecleado en la terminal — la conversación es la misma, da igual por dónde entres.
+
+Los dos puentes funcionan de forma independiente: puedes usar solo Telegram, solo WhatsApp, o los dos a la vez.
+
+### Qué se sincroniza
+
+- **De la terminal al móvil:** tus prompts (`👤`), las respuestas de texto del modelo (`🤖`) y una línea por cada tool call (`🔧 Bash: npm test`, `🔧 Read: src/foo.ts`, etc.). No se manda el output crudo de las herramientas para no saturar el chat.
+- **Del móvil a la terminal:** cualquier texto que envíes aterriza en la cola de entrada del REPL con la misma prioridad que si lo hubieras escrito en la CLI.
+- **Antiduplicado:** si escribes desde el móvil, ese texto no se reenvía de vuelta al mismo canal. El otro canal sí lo recibe (si está activo).
+- **Código no sincronizado:** mensajes internos del sistema, salidas de slash commands y otros eventos auxiliares no se envían a los canales.
+
+### `/telegram` — Bridge con Telegram
+
+Usa la [Bot API oficial de Telegram](https://core.telegram.org/bots/api) vía `grammy`. Requiere crear un bot en **@BotFather** y darle al wizard el token.
+
+Flujo en 3 pasos:
+
+1. **Intro** con instrucciones para crear el bot en `@BotFather` (`/newbot`, nombre, username, token).
+2. **Pegar el token** — input con validación de formato `123456789:ABC-...`.
+3. **Iniciar bot** — el bridge queda corriendo.
+
+Desde el móvil, envía `/start` al bot y ese chat queda registrado como destinatario primario. El bot también responde a `/status`, `/model <nombre>` y `/provider <nombre>` para cambiar proveedor o modelo desde Telegram.
+
+Comandos dentro de la CLI:
+
+```
+/telegram   # abre el wizard (alias: /tele, /bot)
+```
+
+El token queda guardado localmente en la config (`~/.context/...`) y nunca sale del equipo.
+
+### `/whatsapp` — Bridge con WhatsApp
+
+Usa **Baileys** (`@whiskeysockets/baileys`) vía WhatsApp Web para vincular una cuenta como dispositivo enlazado. Baileys es **opcional**: solo se carga cuando ejecutas `/whatsapp` por primera vez, así no pesa en la instalación base. El QR se dibuja en la terminal usando el paquete `qrcode`, ya incluido en el proyecto.
+
+> ⚠️ **Aviso importante.** Baileys es una librería no-oficial. Conectarse por esta vía viola los Términos de Servicio de WhatsApp. Para uso personal en un proyecto privado rara vez pasa nada, pero el número que uses podría ser baneado por WhatsApp en casos extremos. Se recomienda usar un **número dedicado para el bot** (eSIM, número secundario, etc.), no tu WhatsApp personal.
+
+Flujo en 5 pasos:
+
+1. **Intro + aviso de riesgo.**
+2. **Escanear QR** — el wizard dibuja el QR en la terminal. En el móvil del bot: WhatsApp → *Dispositivos Vinculados* → *Vincular un dispositivo* → escaneas.
+3. **Tu número (destinatario primario)** — el número en formato E.164 (`+573001234567`) donde quieres recibir el espejo. También puedes saltar y el primer número que escriba al bot se auto-registra.
+4. **Allowlist de números autorizados** — agregas los números que pueden escribirle al bot. Los mensajes de números fuera de la lista se ignoran en silencio.
+5. **Iniciar bridge** — el bridge queda corriendo.
+
+Desde el panel de ejecución puedes detener el bridge, gestionar la lista de autorizados o cambiar el destinatario sin reiniciar.
+
+Comandos dentro de la CLI:
+
+```
+/whatsapp   # abre el wizard (alias: /wa, /whats)
+```
+
+Las credenciales de sesión de WhatsApp Web se guardan como archivos en `~/.context/whatsapp-auth/` (respetando `CLAUDE_CONFIG_DIR` si está definido), porque Baileys necesita manejar ese directorio de auth. La configuracion lógica del bridge, como destinatario primario, allowlist, identidad vinculada y estado `running`, se guarda en SQLite mediante `secure_storage` en Windows/Linux.
+
+### Configuración guardada
+
+Ambos bridges persisten su configuracion en el storage seguro. En Windows/Linux esto vive cifrado dentro de `~/.context/provider-state.sqlite3`; en macOS se mantiene el backend de keychain/fallback disponible.
+
+```jsonc
+{
+  "telegramBot": {
+    "token": "…",
+    "allowedUserIds": [123456],
+    "primaryChatId": 123456,
+    "isRunning": true
+  },
+  "whatsappBot": {
+    "authDir": "~/.context/whatsapp-auth",
+    "primaryRecipient": "+573001234567",
+    "allowedNumbers": ["+573001234567", "+573109876543"],
+    "selfJid": "573...@s.whatsapp.net",
+    "selfE164": "+573...",
+    "running": true
+  }
+}
+```
+
+Si existe configuracion vieja en el archivo JSON global, se migra automaticamente al leer o actualizar el bridge y se elimina esa clave legacy para evitar dos fuentes de verdad.
+
+### Ritmo de envío
+
+Cada canal usa una cola con throttling para no dispararse contra los rate limits de la plataforma:
+
+- **Telegram:** 150 ms entre mensajes (~6 msg/s, bien por debajo del límite oficial de 30 msg/s por bot).
+- **WhatsApp:** 500 ms entre mensajes (más conservador — Baileys no publica límites formales y enviar demasiado rápido puede disparar shadow-bans).
+
+Si escribes prompts muy rápido la cola se llena hasta 200 items, y a partir de ahí descarta el más viejo para no crecer sin límite.

package/docs/Contex.md

@@ -0,0 +1,70 @@
+# Contex.md — Instrucciones para Claude
+
+## Descripción del Proyecto
+
+Este proyecto es **Context Code** (`@context-ai/context-code`), una herramienta de línea de comandos que permite a Claude entender bases de código, editar archivos, ejecutar comandos de terminal y gestionar flujos de trabajo completos directamente desde la terminal.
+
+- **Versión actual:** 2.1.88
+- **Binario principal:** `context` (via `cli.js`)
+- **Lenguaje:** TypeScript (ES2022, módulos ESM)
+- **Runtime:** Node.js >= 18.0.0
+
+## Estructura del Proyecto
+
+```
+src/
+  assistant/        # Lógica del asistente principal
+  cli/              # Punto de entrada CLI
+  commands/         # Definición de comandos disponibles
+  components/       # Componentes de UI (Ink/React)
+  context/          # Gestión del contexto de conversación
+  coordinator/      # Coordinación de tareas y costos
+  entrypoints/      # Puntos de entrada de la aplicación
+  hooks/            # Hooks personalizados
+  plugins/          # Sistema de plugins
+  query/            # Motor de consultas (QueryEngine)
+  screens/          # Pantallas de la interfaz
+  services/         # Servicios externos e internos
+  skills/           # Habilidades del agente
+  state/            # Gestión de estado
+  tasks/            # Sistema de tareas
+  tools/            # Herramientas disponibles para el agente
+  utils/            # Utilidades generales
+```
+
+## Comandos de Desarrollo
+
+```bash
+npm run typecheck          # Verificar tipos TypeScript
+npm run build              # Compilar el proyecto
+npm run dev:build          # Alias de build
+npm run dev:watch          # Compilar en modo watch
+npm run dev:run            # Ejecutar versión de desarrollo
+npm run start              # Ejecutar la versión compilada
+```
+
+## Sistema de Proveedores
+
+El proyecto ya no debe asumirse como proveedor-unico. La capa actual distingue entre proveedor activo y perfil activo:
+
+- `provider profiles` guardan base URL, ultimo modelo y credenciales cuando aplica.
+- `agentName` queda reservado como nombre operativo para futuros subagentes.
+- los proveedores visibles ya resuelven perfiles de forma compatible; `ollama` y `zai` fueron la primera migracion completa y el resto usa fallback a la configuracion anterior.
+- La configuracion anterior sigue sirviendo como fallback para no romper instalaciones existentes.
+
+## Convenciones de Código
+
+- **TypeScript estricto desactivado** (`strict: false`), pero mantener buenas prácticas de tipado.
+- **Módulos ESM** (`"type": "module"`), usar `import`/`export` siempre.
+- **Resolución de módulos:** `NodeNext` — incluir extensiones en imports cuando sea necesario.
+- **JSX:** `react-jsx` (usado con Ink para la UI de terminal).
+- **Sin comentarios innecesarios** en el código a menos que se soliciten explícitamente.
+- Mantener cambios **mínimos y enfocados** en la tarea solicitada.
+- Respetar el estilo de formato existente (indentación, espacios, etc.).
+
+## Notas Importantes
+
+- No publicar el paquete directamente; el proceso de publicación requiere la variable de entorno `AUTHORIZED`.
+- `tsconfig.json` se usa para compilaciones del proyecto y `tsconfig.typecheck.json` para validación de tipos.
+- Los archivos de distribución se generan en `dist/`.
+- Consultar `RECOVERY_NOTES.md` y `RENAMING_NOTES.md` para contexto histórico del proyecto.

package/docs/LIMITS.md

@@ -0,0 +1,37 @@
+## Limites y uso por proveedor
+
+`/limites` (alias `/limits`) consulta cada proveedor configurado y te muestra cuanto has consumido, cuanto te queda y los limites de tu plan, en una sola vista.
+
+```sh
+/limites
+```
+
+Que hace:
+
+1. Itera sobre todos los `provider profile` que tienes guardados.
+2. Para cada uno, si hay un adapter implementado, llama a su API real en paralelo (con timeout).
+3. Suma a la respuesta el contador local de tokens del CLI: cuantos tokens ha consumido este perfil en la sesion actual y en el historico persistido en SQLite.
+
+Estado de cada proveedor:
+
+| Proveedor      | Que se consulta                                                                                                       |
+|----------------|-----------------------------------------------------------------------------------------------------------------------|
+| Claude (OAuth) | `GET /api/oauth/usage` -> ventanas (5h/7d/Opus/Sonnet) y extra usage. Reusa el cliente que alimenta a `/usage`         |
+| Anthropic API  | `no-data` — solo headers `anthropic-ratelimit-*` por llamada                                                          |
+| OpenAI OAuth   | `no-data` — Codex/ChatGPT solo exponen rate limits dentro del `TokenCountEvent` de cada respuesta del modelo          |
+| OpenAI API     | `GET /v1/usage` (requiere admin key); si la key no tiene permiso, `no-data`                                           |
+| OpenRouter     | `GET /api/v1/auth/key` -> creditos, limite, rate limit                                                                |
+| MiniMax        | `GET /v1/token_plan/remains` -> uso por modelo (endpoint reverse-engineered desde MiniMax-AI/cli `mmx quota show`)    |
+| Z.AI           | `GET /api/monitor/usage/quota/limit` -> tokens usados/limite del coding plan                                          |
+| Ollama local   | Siempre `ok` (ilimitado, corre en tu maquina); cuenta modelos disponibles                                             |
+| Ollama Cloud   | `no-data` salvo localhost                                                                                             |
+
+El contador local de tokens funciona para todos los proveedores por igual: se persiste en `~/.context/provider-state.sqlite3` y te permite saber cuanto has gastado aunque el proveedor no exponga API. La cuenta empieza en cero la primera vez que ejecutas `/limites` despues de instalar.
+
+Comandos relacionados:
+
+```sh
+/limites          # vista interactiva por proveedor
+/usage            # solo Claude: limites del plan vistos por Settings
+/cost             # costo de la sesion actual
+```

package/docs/MCP_SERVERS.md

@@ -0,0 +1,51 @@
+## Servidores MCP externos
+
+Context Code soporta el [Model Context Protocol](https://modelcontextprotocol.io). Puedes conectar servidores MCP de terceros para dar a los agentes herramientas extra: leer una base de datos, consultar Sentry, hablar con tu wiki interna, etc.
+
+Comandos:
+
+```sh
+/mcp                                           # abre el panel de servidores configurados
+/mcp add <name> -- <command> [args...]         # registra un servidor stdio
+/mcp add --transport http <name> <url>         # registra un servidor HTTP
+/mcp add --transport sse <name> <url>          # registra un servidor SSE
+```
+
+Tambien puedes registrar servidores con `--scope project` (escribe en `.mcp.json` del proyecto) o `--scope user` (queda solo para tu usuario). El default es `project` cuando estas dentro de un repo y `user` cuando no.
+
+### Ejemplo: conectar una base de datos SQLite
+
+Existen servidores MCP listos para hablar con bases de datos. El mas conocido es `mcp-server-sqlite`. Lo instalas y lo registras:
+
+```sh
+# 1. Instalar el servidor (o usar npx para no instalar)
+pip install mcp-server-sqlite
+
+# 2. Registrarlo en Context Code apuntando a tu DB
+/mcp add sqlite-local -- mcp-server-sqlite --db-path ./data/app.sqlite
+```
+
+A partir de ese momento, los agentes que ejecuten en este proyecto pueden listar tablas, hacer SELECT y describir el esquema sin que tu tengas que escribir SQL ni copiar/pegar resultados.
+
+### Ejemplo: conectar Postgres
+
+```sh
+# Con uvx (recomendado, sin instalacion previa)
+/mcp add postgres-prod --transport stdio -- uvx mcp-server-postgres \
+  --connection-string "postgres://user:pass@localhost:5432/mydb"
+
+# O con un servidor HTTP ya desplegado
+/mcp add postgres-prod --transport http https://mcp.midominio.com/postgres \
+  --header "Authorization: Bearer $TOKEN"
+```
+
+Pasos a tener en cuenta:
+
+- Los servidores MCP corren con tus permisos. Si conectas a una DB de produccion, considera dar al servidor solo credenciales de lectura.
+- Variables sensibles: usa `-e VAR=valor` al registrar el server stdio para inyectar tokens sin que queden en el comando visible.
+- Las herramientas MCP aparecen en los agentes con prefijo `mcp__<name>__<tool>`. Puedes restringir cuales se autorizan con `--allowedTools` al iniciar la sesion.
+- Si un equipo (`database`, por ejemplo) tendria que usar este MCP, asignale un agente con `/team equipo <team> database <provider>/<agent>` y el orquestador local lo invocara cuando el plan lo requiera.
+
+### Diferencia con el storage interno
+
+El archivo `~/.context/provider-state.sqlite3` es persistencia interna del CLI (perfiles, runs, credenciales). **No es un MCP** y los agentes no lo consultan directamente; solo el runtime lo lee/escribe. Si quieres exponer datos de una base **a los agentes**, registra un servidor MCP como en los ejemplos de arriba.

package/docs/MULTI_PROVIDER.md

@@ -0,0 +1,201 @@
+## Sistema multi-proveedor y multi-perfil
+
+Context Code ya funciona con una capa de proveedores mas flexible. La idea base es separar:
+
+- el `provider` como backend de inferencia
+- el `provider profile` como perfil guardado dentro de ese proveedor
+- el `agentName` como nombre operativo pensado para futuros subagentes
+
+### Provider profile
+
+Un `provider profile` es una configuracion persistida para un proveedor concreto. Sirve para guardar datos que quieres recordar por separado, por ejemplo:
+
+- base URL
+- ultimo modelo usado
+- credenciales o token, cuando el proveedor lo soporta
+
+El nombre del perfil es el identificador humano que ves en el comando. El `agentName` es el nombre tecnico que queda preparado para el futuro sistema de subagentes. Por ejemplo:
+
+```sh
+/provider ollama profile local
+```
+
+Puede guardar un perfil llamado `local` con un `agentName` del estilo `ollama-local`.
+
+### Comando `/provider`
+
+El comando `/provider` ahora sirve para cambiar de proveedor y tambien para activar un perfil concreto.
+
+```sh
+/provider
+/provider list
+/provider ollama
+/provider zai profile main
+/provider ollama profile local
+```
+
+Comportamiento de `/provider`:
+
+- `/provider` (sin argumentos) abre el selector interactivo de proveedores.
+- `/provider list` muestra una tabla detallada con todos tus proveedores, perfiles guardados, estado de conexión (Conectado/Desconectado) y perfiles activos.
+- `/provider <proveedor>` cambia al proveedor especificado.
+- `/provider <proveedor> profile <nombre>` activa (o crea) un perfil específico para ese proveedor.
+- `/provider <proveedor> <URL>` cambia la Base URL del proveedor (ej. `/provider ollama http://localhost:11434/v1`).
+- `/provider <proveedor> clear` restaura la URL por defecto del proveedor.
+
+Tambien existe `/profile` para inspeccionar y navegar perfiles ya guardados:
+
+```sh
+/profile
+/profile list
+/profile current
+/profile use ollama local
+/profile rename ollama local gpu-lab
+/profile model ollama gpu-lab llama3.2
+/profile model ollama gpu-lab clear
+/profile agent ollama gpu-lab ollama-lab
+/profile remove all
+/profile remove ollama gpu-lab
+```
+
+Comportamiento de `/profile`:
+
+- `/profile` o `/profile list` muestra todos los perfiles guardados por proveedor.
+- `/profile current` muestra el perfil activo.
+- `/profile use <proveedor> <perfil>` activa el perfil y restaura su ultimo modelo si existe.
+- `/profile rename <proveedor> <actual> <nuevo>` renombra el perfil.
+- `/profile model <proveedor> <perfil> <modelo>` corrige o fija el ultimo modelo guardado para ese perfil.
+- `/profile model <proveedor> <perfil> clear` limpia el modelo guardado.
+- `/profile agent <proveedor> <perfil> <agentName>` cambia el nombre tecnico del perfil para futuros subagentes.
+- `/profile remove <proveedor> <perfil>` elimina el perfil.
+- `/profile remove all` elimina todos los perfiles guardados de una sola vez.
+
+Notas importantes:
+
+- El nombre visible del perfil y el `agentName` no son lo mismo.
+- El nombre visible sirve para navegar con `/provider ... profile ...` o `/profile use ...`.
+- `agentName` queda reservado como identificador operativo para el futuro sistema de subagentes.
+- Al renombrar un perfil, sus credenciales por perfil tambien se mueven al nuevo identificador para no perder API keys u OAuth.
+- Al borrar un perfil, tambien se limpian sus credenciales scoped cuando existen.
+- `/profile remove all` limpia todos los perfiles y sus credenciales scoped asociadas, pero no toca los fallbacks legacy de compatibilidad.
+
+Comportamiento esperado:
+
+- `/provider` abre la seleccion de proveedor.
+- `/provider <proveedor>` cambia al proveedor activo.
+- `/provider <proveedor> profile <nombre>` selecciona o crea ese perfil y lo deja activo.
+- La configuracion de ese perfil se reutiliza la proxima vez que vuelvas al mismo proveedor o perfil.
+
+Despues de activar un perfil, puedes seguir ajustando sus valores con los comandos normales del proveedor:
+
+```sh
+/provider ollama http://localhost:11434/v1
+/provider ollama clear
+/provider list
+/model
+```
+
+### Soporte Multi-cuenta real
+
+Context Code permite gestionar múltiples cuentas del mismo proveedor (como varias cuentas de Claude o OpenAI) de forma independiente.
+
+```sh
+/login --profile personal
+/login --profile trabajo
+```
+
+- Al usar el flag `--profile` (o `-p`), las credenciales se guardan específicamente en ese perfil.
+- El sistema detecta automáticamente si el perfil ya existe o crea uno nuevo.
+- Puedes saltar entre cuentas fácilmente usando `/provider claude profile personal` o listarlas todas con `/provider list`.
+
+### Persistencia por perfil
+
+La persistencia queda separada por perfil cuando el proveedor lo soporta.
+
+- `base URL` queda guardada por perfil.
+- `ultimo modelo` queda guardado por perfil.
+- `credenciales` quedan guardadas por perfil cuando aplica, incluyendo OAuth y API keys.
+- Si no existe un perfil nuevo, el sistema intenta reutilizar o migrar la configuracion vieja para no romper instalaciones existentes.
+
+### SQLite autogenerable
+
+La metadata de proveedores y perfiles ahora se apoya en una base SQLite autogenerable:
+
+- archivo: `~/.context/provider-state.sqlite3`
+- se crea sola al arrancar si no existe
+- si hay configuracion legacy previa, puede migrarla con `/profile migrate`
+- en Windows/Linux, las credenciales de proveedores tambien se almacenan en esta misma DB
+- esas credenciales se guardan cifradas localmente antes de persistirse en `secure_storage`
+
+Que se guarda ahi:
+
+- perfiles por proveedor
+- perfil activo
+- proveedor activo
+- ultimo modelo por proveedor
+- estado runtime necesario para restaurar contexto rapido
+- API keys, tokens OAuth y credenciales scoped por perfil, mediante la tabla `secure_storage`
+- el contenido de `secure_storage.value` ya no queda en JSON legible; se cifra localmente antes de escribirse
+
+Migracion de credenciales:
+
+- si existe `~/.context/.credentials.json`, se importa automaticamente a SQLite la primera vez que se lee el storage seguro
+- si la importacion termina bien, el archivo legacy `.credentials.json` se elimina para evitar dos fuentes de verdad
+- en macOS se mantiene el flujo de keychain con fallback, segun el backend disponible
+
+Estado actual:
+
+- Windows/Linux ya trabajan en modo `SQLite-only` para providers, perfiles, modelos, base URLs y credenciales
+- `/status` y `/profile migrate` muestran si el runtime quedo completamente migrado
+- macOS sigue usando keychain/fallback por diseno; esa ruta queda fuera de esta migracion
+
+### Proveedores actuales
+
+Estos son los proveedores visibles hoy y su estado general:
+
+- `Claude (Anthropic)`: usa OAuth y ahora puede resolver sesion por perfil, manteniendo fallback al storage anterior.
+- `OpenAI / Codex`: usa OAuth por perfil con compatibilidad hacia atras.
+- `OpenRouter`: usa API key y endpoint configurable por perfil.
+- `Ollama Local`: ya trabaja con perfiles; no usa API key y guarda base URL y modelo por perfil.
+- `Ollama Cloud`: usa endpoint configurable y queda alineado con la capa de perfiles.
+- `Z.AI`: ya trabaja con perfiles; guarda API key, base URL y modelo por perfil.
+- `MiniMax`: usa API key y endpoint compatible con Anthropic por perfil.
+
+### Compatibilidad hacia atras
+
+La migracion esta pensada para no romper la configuracion anterior:
+
+- los valores anteriores pueden servir de base para crear el perfil por defecto durante la migracion inicial
+- `/profile migrate` limpia el remanente legacy cuando la DB ya quedo consistente
+- en Windows/Linux el objetivo final ya es `SQLite-only`
+
+### Notas de uso
+
+- `Ollama` esta pensado como backend local, con el default en `http://localhost:11434/v1`.
+- `Z.AI` requiere API key por perfil y es el primer proveedor no local con soporte real de perfiles.
+- `Claude`, `OpenAI`, `OpenRouter`, `MiniMax` y `Ollama Cloud` ya resuelven su estado desde la arquitectura nueva con fallback a la configuracion anterior.
+- El comando `/model` sigue existiendo y ahora debe entenderse junto con el perfil activo.
+
+## Datos guardados en SQLite
+
+La base se crea automaticamente en:
+
+```text
+~/.context/provider-state.sqlite3
+```
+
+Ademas de perfiles y credenciales de providers, ahi se guardan:
+
+- `provider_workspaces`: proveedores disponibles para equipos
+- `provider_agents`: agentes por proveedor/perfil
+- `provider_agent_capabilities`: capacidades declaradas de agentes
+- `teams`: equipos
+- `team_units`: equipos internos dentro de un team
+- `team_unit_members`: miembros de cada equipo interno
+- `orchestration_runs`: ejecuciones
+- `orchestration_tasks`: tareas
+- `orchestration_messages`: bitacora de decisiones y eventos
+- `orchestration_task_results`: resultados por tarea
+- `orchestration_team_reports`: reportes por equipo interno
+- `orchestration_run_reports`: reporte consolidado de una ejecucion
+- `secure_storage`: credenciales cifradas y configuracion sensible de providers, Telegram y WhatsApp en Windows/Linux