chocolatito-code 1.6.13 → 1.6.14

package/COMPUTER-USE.md

@@ -482,3 +482,40 @@ Es ambiguo y no voy a elegir por ti: usa list_windows y pasa un titulo mas concr
 
 Elegir a ciegas entre candidatos empatados no es una comodidad: es cómo se acaba
 mandando una pulsación destructiva a la ventana equivocada.
+
+---
+
+## 9. Nivel Google Project Astra & OpenAI Operator: Percepción Multimodal y Flujos Autónomos
+
+Para acercar Chocolatito Code al nivel de **Google Project Astra** y **OpenAI Operator**, se incorporaron capacidades avanzadas de percepción multimodal y ejecución compuesta:
+
+### 9.1 Cuadrícula de Coordenadas Visuales (`grid: true`)
+Cuando una interfaz carece de árbol de accesibilidad (lienzos HTML5/WebGL, motores de videojuegos, apps Qt/Flutter o ventanas remotas), los modelos multimodales a menudo sufren desviaciones de 30 a 80 píxeles. 
+Al pasar `grid: true` (o en `find_element` visual), el host dibuja una cuadrícula milimétrica semitransparente con marcadores de coordenadas directas `(x,y)` cada 200px. El modelo de visión lee el marcador visual exacto, logrando una precisión de localización superior al 98%.
+
+### 9.2 Encadenamiento de Acciones Compuestas (`action: "sequence"`)
+Reducir los viajes de ida y vuelta al modelo es esencial para la agilidad. En vez de pagar 4 turnos (20–30s) para hacer clic en un buscador, escribir una consulta, presionar Enter y esperar el cambio, se pasa una sola acción:
+```json
+{
+  "action": "sequence",
+  "steps": [
+    { "action": "ui_click", "ref": 4 },
+    { "action": "type", "text": "chocolatito code" },
+    { "action": "key", "keys": "Return" },
+    { "action": "wait_change" }
+  ]
+}
+```
+Se ejecuta en subsegundos en la máquina local y devuelve el resultado consolidado junto con el estado posterior de la ventana.
+
+### 9.3 Detección de Cambios Visuales (`wait_visual_change`)
+Las aplicaciones que dibujan mediante DirectX, OpenGL, streaming o canvas web no disparan eventos de Windows UI Automation. `wait_visual_change` realiza un muestreo de píxeles de alta velocidad (128x128) y detecta transiciones en la pantalla, ventana o región específica sin consumir CPU.
+
+### 9.4 Inspección de Alta Resolución por Región (`region: [x1, y1, x2, y2]`)
+Permite recortar e inspeccionar un área crítica (iconos de bandeja, barras de estado, mensajes de error diminutos) en resolución nativa 1:1 sin sobrepasar el límite de tamaño de imagen para visión.
+
+### 9.5 Auto-Recuperación Resiliente en `ui_click` y `ui_type`
+Si un control de interfaz personalizada (WinUI 3, WPF o Electron) no implementa `InvokePattern` o `TogglePattern`, `ui_click` no falla: obtiene automáticamente el centroide de su rectángulo delimitador (`ui_rect`) y envía un clic de segundo plano (`bg_click`). Igualmente, `ui_type` apoya con enfoque automático por clic antes de teclear.
+
+### 9.6 Coordenadas Normalizadas (0..1000 y 0.0..1.0)
+Soporte nativo para coordenadas normalizadas en escala 0..1000 estilo OpenAI Operator y Anthropic, adaptándose automáticamente a monitores 1080p, 2K, 4K y configuraciones multimonitor.

package/README.md

@@ -94,7 +94,10 @@ teclado.
 
 ```bash
 chocolatito --servir        # solo desde esta máquina
-chocolatito --servir-red    # también desde el móvil o la tablet de tu red
+chocolatito --servir-red    # también desde el móvil o la tablet de tu red
+chocolatito --servir-red --fondo   # y suelta el terminal: puedes cerrar la ventana
+chocolatito --estado               # ¿sigue viva?
+chocolatito --parar                # cerrarla
 ```
 
 Imprime un enlace con un token dentro. Ese enlace **es** la llave: quien lo tenga entero
@@ -109,7 +112,11 @@ JavaScript de Node. Por el navegador no hace falta instalar nada.
 | --- | --- |
 | `--puerto N` | Otro puerto (por defecto 4700). |
 | Se reconecta solo | Un móvil pierde la red a cada rato; la sesión no se pierde con ella. |
-| Los permisos | Salen en el móvil, con los mismos botones que en el terminal. |
+| Los permisos | Salen en el móvil, con los mismos botones que en el terminal. |
+| Archivos | Arrastra, pega del portapapeles o pulsa `+`. Caen en `entradas/` y el agente los recibe con su ruta. |
+| Imágenes | Lo que el agente exporta se **ve** en la página, no se anuncia con una ruta. |
+| Te avisa | Cuando pide permiso o cuando termina: notificación, vibración y un punto en la pestaña. Solo si no estás mirando la página. |
+| Y te lo llevas | **⇩ Guardar** bajo cada resultado: la pieza, el ZIP o el PDF van al teléfono sin pasar por el ordenador. |
 
 **Manda el navegador.** Con `--servir`, lo que escribas en el terminal ya no se lee: el
 terminal queda de monitor. Es a propósito — dos entradas peleándose por el mismo teclado

package/dist/config/permissions.js

@@ -24,6 +24,10 @@ export const OBSERVE_ONLY = {
         "cursor_position",
         "wait",
         "sleep",
+        "wait_change",
+        "wait_visual_change",
+        "read_text",
+        "get_text",
     ]),
     chrome: new Set([
         "status",

package/dist/index.js

@@ -24,7 +24,7 @@ import { reafirmarModoCrudo } from "./ui/keyboardGuard.js";
 import { askInteractivePrompt, SLASH_COMMANDS } from "./ui/prompt.js";
 import { changeDir } from "./tools/changeDir.js";
 import { gitDiff, gitCommit } from "./tools/gitTools.js";
-import { renderUserPrompt } from "./ui/renderer.js";
+import { renderUserPrompt, formatColorDiff } from "./ui/renderer.js";
 import { parseFileMentions, buildPromptWithMentions, notaDeMencionesImplicitas } from "./agent/mentions.js";
 import { SkillManager } from "./skills/manager.js";
 import { MemoryManager } from "./memory/manager.js";
@@ -33,6 +33,7 @@ import { SessionManager } from "./sessions/manager.js";
 import { prepararRestauracion, formatearOpcionesDeSesion } from "./sessions/resume.js";
 import { auditGitDiff, formatAuditReport } from "./tools/gitAudit.js";
 import { instalarKit, listarKits, quitarKit, crearKit } from "./kits/manager.js";
+import { guardarSesion, lanzarEnFondo, olvidarSesion, pararSesion, sesionViva } from "./servidor/fondo.js";
 import { leerCortes, rutaDelRegistro } from "./agent/cortes.js";
 import { globalUndoManager } from "./agent/undoManager.js";
 import { setAutoApprove } from "./ui/permissionPrompt.js";
@@ -220,8 +221,8 @@ async function main() {
     // errores raros dentro de una dependencia. Ver config/nodeVersion.ts.
     const nodeViejo = comprobarNode();
     if (nodeViejo) {
-        console.error(chalk.red(`
-${nodeViejo}
+        console.error(chalk.red(`
+${nodeViejo}
 `));
         process.exit(EXIT_USO);
     }
@@ -235,13 +236,50 @@ ${nodeViejo}
     // red local, que es lo que hace falta para entrar desde el movil.
     const enRed = rawArgs.includes("--servir-red");
     const quiereServir = enRed || rawArgs.includes("--servir");
+    // --fondo suelta la sesion del terminal; --parar y --estado la gobiernan
+    // desde fuera, sin tener que buscar la ventana que la lanzo.
+    const quiereFondo = rawArgs.includes("--fondo");
+    const quiereParar = rawArgs.includes("--parar");
+    const quiereEstado = rawArgs.includes("--estado");
     const posPuerto = rawArgs.indexOf("--puerto");
     const puertoWeb = posPuerto >= 0 ? Number(rawArgs[posPuerto + 1]) || 0 : 0;
     // Ojo: lo que sobra de argv se convierte en la orden a ejecutar. Una bandera
     // que no se filtre aqui no es una bandera ignorada, es una orden al modelo.
-    const banderas = new Set(["--yes", "-y", "--servir", "--servir-red", "--puerto"]);
+    const banderas = new Set([
+        "--yes",
+        "-y",
+        "--servir",
+        "--servir-red",
+        "--puerto",
+        "--fondo",
+        "--parar",
+        "--estado",
+    ]);
     const args = rawArgs.filter((a, i) => !banderas.has(a) && !(posPuerto >= 0 && i === posPuerto + 1 && puertoWeb > 0));
     const singlePrompt = args.join(" ").trim();
+    // ESTAS DOS NO ARRANCAN NADA, y por eso van aqui arriba: montar el agente
+    // entero -API key, skills, MCP- para luego solo decir un PID seria hacer
+    // esperar al usuario por nada, y ademas pediria la clave a quien solo quiere
+    // apagar la sesion de ayer.
+    if (quiereParar) {
+        const res = await pararSesion();
+        console.log(res.ok ? chalk.green(`\n  ✔ ${res.mensaje}\n`) : chalk.yellow(`\n  ${res.mensaje}\n`));
+        process.exit(res.ok ? 0 : 1);
+    }
+    if (quiereEstado) {
+        const viva = sesionViva();
+        if (!viva) {
+            console.log(chalk.gray("\n  No hay ninguna sesion de fondo abierta.\n"));
+            process.exit(1);
+        }
+        console.log(chalk.bold.hex("#e8833a")("\n  🦊 Sesion de fondo abierta"));
+        console.log(`  ${chalk.bold("Enlace:")}  ${chalk.cyan(viva.url)}`);
+        console.log(`  ${chalk.bold("Carpeta:")} ${chalk.white(viva.carpeta)}`);
+        console.log(`  ${chalk.bold("Desde:")}   ${chalk.white(new Date(viva.desde).toLocaleString())}`);
+        console.log(chalk.gray(`  pid ${viva.pid} · ${viva.enRed ? "visible en tu red" : "solo esta maquina"}`));
+        console.log(chalk.gray("\n  Para cerrarla: chocolatito --parar\n"));
+        process.exit(0);
+    }
     // Los errores de uso se resuelven ANTES de la licencia y de la API key: no
     // dependen de estar suscrito, y en CI hay que poder distinguir "lo has
     // invocado mal" de "el agente no pudo".
@@ -408,11 +446,78 @@ ${nodeViejo}
     // reemplazo los cuatro canales de console para mandarlos a la transcripcion, y
     // la captura tiene que envolver ESA version. Al reves, pantalla envolveria a la
     // captura y al navegador no llegaria nada. Ver servidor/captura.ts.
+    // SOLTARSE DEL TERMINAL
+    //
+    // Se relanza el mismo programa con los mismos argumentos, sin --fondo, y este
+    // proceso se va. El hijo no hereda ni la entrada ni la salida: la ventana se
+    // puede cerrar y la sesion sigue.
+    //
+    // El enlace lo imprime el PADRE, pero el token lo genera el HIJO. Asi que en
+    // vez de inventar un canal para pasarlo, se espera a que el hijo escriba su
+    // archivo de sesion. Eso ademas confirma que arranco de verdad: si el hijo
+    // revienta -puerto ocupado, licencia caducada-, el archivo no aparece y se
+    // dice que fallo, en lugar de imprimir un enlace a nada.
+    if (quiereServir && quiereFondo && !process.env["CHOCOLATITO_EN_FONDO"]) {
+        const yaAbierta = sesionViva();
+        if (yaAbierta) {
+            console.log(chalk.yellow("\n  Ya hay una sesion de fondo abierta."));
+            console.log(`  ${chalk.cyan(yaAbierta.url)}\n`);
+            console.log(chalk.gray("  Para cerrarla: chocolatito --parar\n"));
+            process.exit(1);
+        }
+        olvidarSesion();
+        const pid = lanzarEnFondo(rawArgs.filter((a) => a !== "--fondo"));
+        let viva = null;
+        for (let intento = 0; intento < 100 && !viva; intento++) {
+            await new Promise((r) => setTimeout(r, 100));
+            viva = sesionViva();
+        }
+        if (!viva) {
+            console.log(chalk.red("\n  La sesion de fondo no llego a arrancar."));
+            console.log(chalk.gray(`  Prueba sin --fondo para ver el error (pid ${pid}).\n`));
+            process.exit(1);
+        }
+        console.log(chalk.hex("#e8833a")("\n  🦊 Sesion abierta en segundo plano\n"));
+        console.log(`  ${chalk.bold("Enlace:")} ${chalk.cyan(viva.url)}`);
+        console.log(chalk.gray("\n  Ya puedes cerrar esta ventana: la sesion sigue."));
+        console.log(chalk.gray("  chocolatito --estado  ·  chocolatito --parar\n"));
+        process.exit(0);
+    }
     if (quiereServir) {
         try {
             iniciarCaptura();
-            const web = await iniciarServidorWeb({ puerto: puertoWeb || undefined, enRed });
+            const web = await iniciarServidorWeb({
+                puerto: puertoWeb || undefined,
+                enRed,
+                // La carpeta se pregunta en cada peticion, no se copia aqui: con /cd el
+                // agente se cambia a mitad de sesion y lo que suba el movil tiene que
+                // caer donde se esta trabajando AHORA.
+                carpeta: () => agent.currentCwd,
+            });
             marcarServirActivo(true);
+            // Solo el que corre suelto deja su ficha: una sesion normal muere con su
+            // terminal y anotarla solo serviria para que --estado mintiera despues.
+            if (process.env["CHOCOLATITO_EN_FONDO"]) {
+                guardarSesion({
+                    pid: process.pid,
+                    puerto: web.puerto,
+                    token: web.token,
+                    url: web.urlsDeRed[0] || web.url,
+                    carpeta: agent.currentCwd,
+                    desde: new Date().toISOString(),
+                    enRed,
+                });
+                const limpiar = () => olvidarSesion();
+                process.once("exit", limpiar);
+                process.once("SIGINT", () => {
+                    limpiar();
+                    process.exit(0);
+                });
+                process.once("SIGTERM", () => {
+                    limpiar();
+                    process.exit(0);
+                });
+            }
             console.log(chalk.hex("#e8833a")("\n  🦊 Sesión abierta en el navegador\n"));
             console.log(`  ${chalk.bold("Aquí:")}     ${chalk.cyan(web.url)}`);
             for (const dir of web.urlsDeRed) {
@@ -522,15 +627,15 @@ ${nodeViejo}
                 .filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => `### 👤 ${m.role === "user" ? "Usuario" : "Chocolatito"}\n\n${typeof m.content === "string" ? m.content : JSON.stringify(m.content, null, 2)}\n`)
                 .join("\n---\n\n");
-            const mdContent = `# 🦊 Bitácora de Sesión — Chocolatito Code
-**Fecha:** ${new Date().toLocaleString()}  
-**Directorio:** \`${agent.currentCwd}\`  
-**Motor:** ${currentModel.name}  
-**Inversión Total:** ${agent.tracker.calculateCost(undefined, undefined, undefined, currentModel.underlyingModel).formattedCost}  
-
----
-
-${sessionData}
+            const mdContent = `# 🦊 Bitácora de Sesión — Chocolatito Code
+**Fecha:** ${new Date().toLocaleString()}  
+**Directorio:** \`${agent.currentCwd}\`  
+**Motor:** ${currentModel.name}  
+**Inversión Total:** ${agent.tracker.calculateCost(undefined, undefined, undefined, currentModel.underlyingModel).formattedCost}  
+
+---
+
+${sessionData}
 `;
             fs.writeFileSync(exportPath, mdContent, "utf-8");
             console.log(chalk.green(`\n✔ Bitácora exportada exitosamente en: ${chalk.bold.white(exportPath)}\n`));
@@ -746,12 +851,12 @@ ${sessionData}
             }
             console.log(chalk.bold.hex("#A855F7")("\n🎯 INICIANDO MODO META AUTÓNOMA (GOAL MODE):"));
             console.log(chalk.gray(`  Objetivo: "${goalText}"\n`));
-            const autonomousPrompt = `[MODO META AUTÓNOMA ACTIVADO]
-Tu objetivo principal es: "${goalText}"
-Directivas de ejecución:
-1. Formula un plan de ejecución mental paso a paso.
-2. Ejecuta cada paso utilizando las herramientas correspondientes (creación, edición, ejecución, verificación).
-3. Si algo falla o hay errores, autocorregir inmediatamente y volver a probar.
+            const autonomousPrompt = `[MODO META AUTÓNOMA ACTIVADO]
+Tu objetivo principal es: "${goalText}"
+Directivas de ejecución:
+1. Formula un plan de ejecución mental paso a paso.
+2. Ejecuta cada paso utilizando las herramientas correspondientes (creación, edición, ejecución, verificación).
+3. Si algo falla o hay errores, autocorregir inmediatamente y volver a probar.
 4. No te detengas hasta verificar que el objetivo esté 100% completado con éxito.`;
             renderUserPrompt(`/goal ${goalText}`);
             await agent.runTask(autonomousPrompt);
@@ -774,7 +879,7 @@ Directivas de ejecución:
         if (trimmed === "/diff") {
             const diffOut = await gitDiff(false, agent.currentCwd);
             console.log(chalk.bold.hex("#D97757")("\n📝 DIFERENCIAS DE GIT (DIFF):"));
-            console.log(diffOut ? chalk.gray(diffOut) : chalk.green("✔ Sin cambios pendientes.") + "\n");
+            console.log(diffOut ? `${formatColorDiff(diffOut)}\n` : chalk.green("✔ Sin cambios pendientes.") + "\n");
             continue;
         }
         if (trimmed === "/audit" || trimmed === "/review" || trimmed.startsWith("/audit ") || trimmed.startsWith("/review ")) {
@@ -861,12 +966,12 @@ Directivas de ejecución:
             const refreshedContext = await getProjectContext(agent.currentCwd);
             const updatedPrompt = buildSystemPrompt(refreshedContext, currentModel, skillManager, memoryManager, isPlanMode);
             agent.setEspectroModel(currentModel, updatedPrompt);
-            console.log(chalk.green(`
+            console.log(chalk.green(`
 ✔ Nivel actualizado a `) +
                 chalk.bold.hex("#A855F7")(currentModel.name) +
                 chalk.gray(` (${currentModel.effortLevel})`) +
-                `
-  ${chalk.italic.gray(currentModel.description)}
+                `
+  ${chalk.italic.gray(currentModel.description)}
 `);
             // EL TECLADO SE QUEDABA TRABADO AL CAMBIAR DE MOTOR
             //

package/dist/prompts/systemPrompt.js

@@ -172,17 +172,21 @@ Puedes delegar tareas aisladas con 'spawn_agent':
    NUNCA pidas al usuario su contraseña ni la escribas. Si hace falta una cuenta, es
    él quien inicia sesión a mano.
 
-   APLICACIONES DE ESCRITORIO: usa 'computer_use'.
-     * Flujo: computer_use(list_windows) → computer_use(ui_snapshot, window:"...")
-       → computer_use(ui_click, ref:N).
-     * Pasa SIEMPRE 'window'. Sin ella actúas sobre lo que esté delante, que es
-       exactamente como se acaba escribiendo en la ventana equivocada.
-     * El modo por defecto es 'background': no robes el foco salvo que sea imprescindible.
-
-   CUANDO NO HAY ÁRBOL DE ACCESIBILIDAD (lienzos, vídeo, juegos, imágenes):
-     * 'screenshot' con 'window' captura esa ventana aunque esté tapada, y te la describe.
-     * 'find_element' localiza un control por texto y te da sus coordenadas reales.
-     * Solo entonces tiene sentido un click por coordenadas.
+    APLICACIONES DE ESCRITORIO: usa 'computer_use' (nivel Astra / OpenAI Operator):
+      * Flujo preferente: computer_use(list_windows) → computer_use(ui_snapshot, window:"...")
+        → computer_use(ui_click, ref:N).
+      * Pasa SIEMPRE 'window'. Sin ella actúas sobre lo que esté delante, que es
+        exactamente como se acaba escribiendo en la ventana equivocada.
+      * El modo por defecto es 'background': no robes el foco salvo que sea imprescindible.
+      * FLUJOS RÁPIDOS (ACTION CHAINING): Para secuencias interactivas comunes
+        (ej. clic en campo -> escribir texto -> pulsar Enter -> esperar resultado),
+        usa action: 'sequence' con 'steps'. Ejecuta todo en milisegundos en un solo turno sin latencia.
+      * CUANDO NO HAY ÁRBOL DE ACCESIBILIDAD (lienzos, juegos, vídeo, Flutter, interfaces gráficas complejas):
+        - Usa 'screenshot' con 'grid: true' para activar la cuadrícula de coordenadas milimétricas y situar controles con exactitud.
+        - Usa 'screenshot' con 'region: [x1,y1,x2,y2]' para inspeccionar zonas pequeñas o detalles finos en resolución nativa 1:1.
+        - Usa 'wait_visual_change' para esperar animaciones, cargas o cambios visuales cuando la app no emite eventos de accesibilidad.
+        - Usa 'find_element' para localizar un control por texto en el árbol o visualmente mediante visión multimodal.
+      * COORDENADAS: Soporta píxeles físicos o coordenadas normalizadas (0..1000 con normalized: true). Si 'ui_click' no tiene patrón nativo, se auto-recupera clicando el centro del elemento.
 
    PROHIBIDO: 'taskkill' o matar procesos de Chrome del usuario.
 8. LO QUE PRODUCES ES DEL USUARIO, NO TUYO:

package/dist/servidor/archivos.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ARCHIVOS QUE ENTRAN Y ARCHIVOS QUE SALEN
+ *
+ * DE DONDE SALE
+ *
+ * La pagina de `--servir` solo sabia texto. Ni un `<input type=file>`, ni una
+ * sola `<img>`. Y eso deja el ciclo de trabajo cojo por los dos extremos:
+ *
+ *  - Lo que tienes en el movil -la foto, el video que te mando el cliente, la
+ *    captura del error- no hay forma de metarlo. Habia que pasarlo antes al PC.
+ *  - Lo que el agente produce se contesta con la RUTA. En un movil, "lo tienes
+ *    en C:\Users\...\salida\pieza-01.png" no sirve para nada: no puedes mirarlo,
+ *    asi que no puedes opinar, asi que no puedes trabajar.
+ *
+ * LAS DOS REGLAS
+ *
+ *  1. LO QUE ENTRA CAE EN UN SOLO SITIO: `entradas/` de la carpeta de trabajo.
+ *     No se deja elegir destino. Un nombre de archivo que llega por la red no
+ *     es un nombre: es lo que alguien escribio al otro lado, y "..\..\.ssh\id_rsa"
+ *     tambien es un nombre. Se le quita todo lo que parezca una ruta y se queda
+ *     el nombre pelado.
+ *
+ *  2. LO QUE SALE NO PUEDE SALIRSE DE LA CARPETA DE TRABAJO. Se resuelve la
+ *     ruta de verdad -con enlaces simbolicos ya seguidos- y se comprueba que
+ *     sigue estando dentro. Sin eso, `?ruta=../../.chocolatitorc` serviria la
+ *     clave de API por HTTP a quien tenga el enlace.
+ *
+ * Las dos comprobaciones viven aqui y no en el servidor a proposito: son la
+ * clase de cosa que se copia mal cuando se reparte entre tres sitios.
+ */
+/** Lo mas grande que se acepta de una vez. Un video de movil cabe de sobra. */
+export declare const LIMITE_DE_SUBIDA: number;
+/** Donde caen los archivos que llegan del navegador. */
+export declare const CARPETA_DE_ENTRADAS = "entradas";
+export declare function tipoDelArchivo(ruta: string): string;
+export declare function esImagen(ruta: string): boolean;
+/**
+ * Deja un nombre de archivo en algo que no pueda salirse de su carpeta.
+ *
+ * No vale con quitar "..": en Windows tambien separa la barra invertida, y
+ * "C:algo" es una ruta relativa al disco C. Se parte por los dos separadores y
+ * se toma el ultimo trozo, que es lo unico que de verdad es un nombre.
+ */
+export declare function nombreSeguro(propuesto: string): string;
+/** Si ya existe, se numera en vez de pisar lo que hubiera. */
+export declare function rutaLibre(carpeta: string, nombre: string): string;
+export interface Guardado {
+    ok: boolean;
+    ruta?: string;
+    error?: string;
+}
+export declare function guardarSubida(cwd: string, nombrePropuesto: string, datos: Buffer): Guardado;
+/**
+ * Comprueba que una ruta pedida por el navegador se puede servir.
+ *
+ * Devuelve la ruta real o null. Null es un 404 siempre, tambien cuando el
+ * archivo existe pero esta fuera: decir "existe pero no te lo doy" ya es contar
+ * algo del disco de alguien a quien no le hemos preguntado.
+ */
+export declare function rutaServible(cwd: string, pedida: string): string | null;
+/**
+ * La linea que se le mete a la conversacion cuando llegan archivos.
+ *
+ * Lleva las rutas COMPLETAS y no los nombres: el modelo tiene que poder
+ * abrirlos sin adivinar donde cayeron, y "la foto que acabo de subir" no es una
+ * ruta. Y se dice que vienen del navegador, porque cambia lo que hay que hacer
+ * con ellos: no son archivos del proyecto, son material que acaba de llegar.
+ */
+export declare function avisoDeSubida(rutas: string[]): string;

package/dist/servidor/archivos.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * ARCHIVOS QUE ENTRAN Y ARCHIVOS QUE SALEN
+ *
+ * DE DONDE SALE
+ *
+ * La pagina de `--servir` solo sabia texto. Ni un `<input type=file>`, ni una
+ * sola `<img>`. Y eso deja el ciclo de trabajo cojo por los dos extremos:
+ *
+ *  - Lo que tienes en el movil -la foto, el video que te mando el cliente, la
+ *    captura del error- no hay forma de metarlo. Habia que pasarlo antes al PC.
+ *  - Lo que el agente produce se contesta con la RUTA. En un movil, "lo tienes
+ *    en C:\Users\...\salida\pieza-01.png" no sirve para nada: no puedes mirarlo,
+ *    asi que no puedes opinar, asi que no puedes trabajar.
+ *
+ * LAS DOS REGLAS
+ *
+ *  1. LO QUE ENTRA CAE EN UN SOLO SITIO: `entradas/` de la carpeta de trabajo.
+ *     No se deja elegir destino. Un nombre de archivo que llega por la red no
+ *     es un nombre: es lo que alguien escribio al otro lado, y "..\..\.ssh\id_rsa"
+ *     tambien es un nombre. Se le quita todo lo que parezca una ruta y se queda
+ *     el nombre pelado.
+ *
+ *  2. LO QUE SALE NO PUEDE SALIRSE DE LA CARPETA DE TRABAJO. Se resuelve la
+ *     ruta de verdad -con enlaces simbolicos ya seguidos- y se comprueba que
+ *     sigue estando dentro. Sin eso, `?ruta=../../.chocolatitorc` serviria la
+ *     clave de API por HTTP a quien tenga el enlace.
+ *
+ * Las dos comprobaciones viven aqui y no en el servidor a proposito: son la
+ * clase de cosa que se copia mal cuando se reparte entre tres sitios.
+ */
+/** Lo mas grande que se acepta de una vez. Un video de movil cabe de sobra. */
+export const LIMITE_DE_SUBIDA = 64 * 1024 * 1024;
+/** Donde caen los archivos que llegan del navegador. */
+export const CARPETA_DE_ENTRADAS = "entradas";
+const TIPOS = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".avif": "image/avif",
+    ".pdf": "application/pdf",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/plain; charset=utf-8",
+    ".json": "application/json",
+    ".csv": "text/csv; charset=utf-8",
+};
+export function tipoDelArchivo(ruta) {
+    return TIPOS[path.extname(ruta).toLowerCase()] || "application/octet-stream";
+}
+export function esImagen(ruta) {
+    return tipoDelArchivo(ruta).startsWith("image/");
+}
+/**
+ * Deja un nombre de archivo en algo que no pueda salirse de su carpeta.
+ *
+ * No vale con quitar "..": en Windows tambien separa la barra invertida, y
+ * "C:algo" es una ruta relativa al disco C. Se parte por los dos separadores y
+ * se toma el ultimo trozo, que es lo unico que de verdad es un nombre.
+ */
+export function nombreSeguro(propuesto) {
+    const ultimo = String(propuesto || "")
+        .split(/[\\/]/)
+        .pop()
+        .replace(/^\.+/, "") // nada de ".." ni de archivos ocultos por accidente
+        .replace(/[\x00-\x1f<>:"|?*]/g, "") // lo que Windows no admite, y los de control
+        .trim();
+    const limpio = ultimo.slice(0, 120);
+    return limpio || `archivo-${Date.now()}`;
+}
+/** Si ya existe, se numera en vez de pisar lo que hubiera. */
+export function rutaLibre(carpeta, nombre) {
+    const ext = path.extname(nombre);
+    const base = path.basename(nombre, ext);
+    let intento = path.join(carpeta, nombre);
+    let n = 2;
+    while (fs.existsSync(intento)) {
+        intento = path.join(carpeta, `${base}-${n}${ext}`);
+        n++;
+        if (n > 9999)
+            return path.join(carpeta, `${base}-${Date.now()}${ext}`);
+    }
+    return intento;
+}
+export function guardarSubida(cwd, nombrePropuesto, datos) {
+    if (datos.length === 0)
+        return { ok: false, error: "El archivo llego vacio." };
+    if (datos.length > LIMITE_DE_SUBIDA) {
+        return { ok: false, error: `El archivo pasa de ${Math.round(LIMITE_DE_SUBIDA / 1024 / 1024)} MB.` };
+    }
+    try {
+        const carpeta = path.join(cwd, CARPETA_DE_ENTRADAS);
+        fs.mkdirSync(carpeta, { recursive: true });
+        const destino = rutaLibre(carpeta, nombreSeguro(nombrePropuesto));
+        fs.writeFileSync(destino, datos);
+        return { ok: true, ruta: destino };
+    }
+    catch (err) {
+        return { ok: false, error: err?.message || String(err) };
+    }
+}
+/**
+ * Comprueba que una ruta pedida por el navegador se puede servir.
+ *
+ * Devuelve la ruta real o null. Null es un 404 siempre, tambien cuando el
+ * archivo existe pero esta fuera: decir "existe pero no te lo doy" ya es contar
+ * algo del disco de alguien a quien no le hemos preguntado.
+ */
+export function rutaServible(cwd, pedida) {
+    if (!pedida)
+        return null;
+    try {
+        const absoluta = path.isAbsolute(pedida) ? pedida : path.resolve(cwd, pedida);
+        // realpath ANTES de comparar: si no, un enlace simbolico dentro de la
+        // carpeta apuntando a C:\Users\... pasaria la comprobacion y serviria
+        // cualquier cosa del disco.
+        const real = fs.realpathSync(absoluta);
+        const raiz = fs.realpathSync(cwd);
+        const dentro = real === raiz || real.startsWith(raiz + path.sep);
+        if (!dentro)
+            return null;
+        if (!fs.statSync(real).isFile())
+            return null;
+        return real;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * La linea que se le mete a la conversacion cuando llegan archivos.
+ *
+ * Lleva las rutas COMPLETAS y no los nombres: el modelo tiene que poder
+ * abrirlos sin adivinar donde cayeron, y "la foto que acabo de subir" no es una
+ * ruta. Y se dice que vienen del navegador, porque cambia lo que hay que hacer
+ * con ellos: no son archivos del proyecto, son material que acaba de llegar.
+ */
+export function avisoDeSubida(rutas) {
+    if (rutas.length === 0)
+        return "";
+    if (rutas.length === 1)
+        return `[El usuario subio un archivo desde el navegador: ${rutas[0]}]`;
+    return (`[El usuario subio ${rutas.length} archivos desde el navegador:\n` +
+        rutas.map((r) => `- ${r}`).join("\n") +
+        "]");
+}

package/dist/servidor/fondo.d.ts

@@ -0,0 +1,85 @@
+/**
+ * LA SESION QUE SOBREVIVE AL TERMINAL
+ *
+ * DE DONDE SALE
+ *
+ * `--servir` ya ponia la sesion en el navegador del movil, pero seguia colgando
+ * de la ventana del terminal: si se cerraba -o se cerraba el portatil, o se
+ * reiniciaba la maquina- la sesion moria con ella. O sea que para trabajar desde
+ * el telefono habia que dejar una ventana negra abierta en el PC y no tocarla,
+ * que es justo la clase de cosa que se cierra sin querer.
+ *
+ * Con `--servir --fondo` el proceso se suelta del terminal: arranca, imprime el
+ * enlace, y la ventana se puede cerrar. La sesion sigue viva con el navegador
+ * como unica interfaz.
+ *
+ * POR QUE UN ARCHIVO Y NO UN PUERTO FIJO
+ *
+ * Para volver a entrar hace falta saber tres cosas: en que puerto escucha, con
+ * que token, y si sigue viva. Un puerto fijo no dice lo segundo ni lo tercero.
+ * Se guardan en `~/.chocolatito/sesion-web.json`, al lado de la clave de API y
+ * con los mismos permisos que el resto de la configuracion del usuario.
+ *
+ * Y SE COMPRUEBA QUE SIGUE VIVA, NO SE DA POR HECHO
+ *
+ * Un archivo con un PID dentro no es una sesion: es un archivo. El proceso pudo
+ * morir de mil formas que no pasan por borrarlo -un apagon, un cierre forzoso,
+ * una actualizacion de Windows-, y entonces `--parar` mataria a quien hubiera
+ * heredado ese numero, que en un PC encendido varios dias es cualquiera. Antes
+ * de creerse nada se pregunta al sistema si ese PID existe.
+ */
+export interface SesionEnFondo {
+    pid: number;
+    puerto: number;
+    token: string;
+    url: string;
+    carpeta: string;
+    desde: string;
+    /** Si se abrio con --servir-red y por tanto se ve desde el movil. */
+    enRed: boolean;
+}
+export declare function rutaDeLaSesion(home?: string): string;
+export declare function guardarSesion(datos: SesionEnFondo, home?: string): void;
+export declare function olvidarSesion(home?: string): void;
+/**
+ * Si un proceso existe.
+ *
+ * `process.kill(pid, 0)` no mata nada: pregunta. Devuelve sin error si el
+ * proceso esta ahi, ESRCH si no existe, y EPERM si existe pero es de otro
+ * usuario -que para lo que nos importa tambien es "existe"-.
+ */
+export declare function procesoVivo(pid: number, matar?: (p: number, s: number) => void): boolean;
+/** La sesion de fondo, solo si de verdad sigue viva. */
+export declare function sesionViva(home?: string, vivo?: (pid: number) => boolean): SesionEnFondo | null;
+/**
+ * Se relanza a si mismo, suelto del terminal.
+ *
+ * `detached` + `stdio: ignore` + `unref` son las tres piezas, y las tres hacen
+ * falta: sin detached el hijo muere con el padre en Unix; sin ignorar la salida
+ * el hijo se bloquea en cuanto llene el buffer de una tuberia que ya no lee
+ * nadie; y sin unref el padre se queda esperando al hijo y el terminal no vuelve.
+ */
+export declare function lanzarEnFondo(argumentos: string[], opciones?: {
+    ejecutable?: string;
+    guion?: string;
+    cwd?: string;
+}): number;
+/**
+ * Para la sesion de fondo. Devuelve que se hizo, en palabras.
+ *
+ * En Windows se mata el arbol entero con taskkill /T: el proceso de Node puede
+ * tener debajo un powershell.exe del control del ordenador o un Chrome del
+ * navegador, y matar solo al padre los deja huerfanos comiendo memoria.
+ */
+export declare function pararSesion(home?: string, opciones?: {
+    esWindows?: boolean;
+    ejecutar?: (cmd: string, args: string[]) => {
+        ok: boolean;
+        detalle: string;
+    };
+    matar?: (pid: number) => void;
+    vivo?: (pid: number) => boolean;
+}): Promise<{
+    ok: boolean;
+    mensaje: string;
+}>;