xonecode 0.38.44 → 0.39.4

package/dist/agent/dispositivos/juezVisual.d.ts

@@ -0,0 +1,144 @@
+import type { Papel } from "../../core/ports.js";
+import { type PantallaDescrita } from "../../core/descripcionDePantalla.js";
+/** El papel del juez, el mismo que el de tareas. `core/modelos.ts` lo reserva para esto. */
+export declare const PAPEL_DEL_JUEZ_VISUAL: Papel;
+/**
+ * Cuántas observaciones se conservan y cuánto ocupa cada una.
+ *
+ * Del mismo orden que las del juez de tareas, y por lo mismo: esto acaba en una tarjeta o en
+ * un mensaje de reparación, no en un informe. No se acota para poder compararlo —no se puede,
+ * ver la cabecera— sino para que quepa.
+ */
+export declare const TOPE_DE_OBSERVACIONES = 15;
+/**
+ * Cuántas pantallas puede pedir de una vez.
+ *
+ * Tiene tope por lo mismo que `TOPE_REPARACIONES`: su salida NO es estable —seis vueltas sobre
+ * la misma captura dieron 4, 2, 4, 5, 3 y 5 observaciones— así que sin acotarlo pediría
+ * pantallas mientras alguien se las traiga, y cada una es un despliegue y una navegación.
+ */
+export declare const TOPE_DE_PETICIONES = 3;
+/** No se pudo PREGUNTAR: no hay modelo, no hay clave, no hay red. */
+export declare class ErrorDelJuezVisual extends Error {
+    constructor(motivo: string);
+}
+/** Una captura, ya en memoria. Nunca una ruta: por aquí no viaja el disco. */
+export interface CapturaDePantalla {
+    base64: string;
+    mime: string;
+}
+export type InvocarVisual = (papel: Papel, prompt: string, imagen: CapturaDePantalla, 
+/**
+ * La MAQUETA contra la que comparar, cuando la hay.
+ *
+ * Va como cuarto parámetro OPCIONAL a propósito, el molde de `fase?` y `razonamiento?` en
+ * `Piel`: una implementación con menos parámetros sigue asignándose a este tipo, así que
+ * `cli/main.ts`, `cli/run.ts` y los dobles de los tests no cambian de una línea.
+ */
+referencia?: CapturaDePantalla) => Promise<string>;
+export interface VeredictoVisual {
+    veredicto: "verde" | "rojo" | "indeterminado";
+    /**
+     * Lo que SE VE, en palabras del modelo. No son hallazgos: no llevan fichero, no llevan
+     * línea, y su explicación de la causa está medida como poco fiable.
+     */
+    observaciones: string[];
+    /**
+     * Qué OTRAS pantallas necesita ver, por nombre de colección.
+     *
+     * Es lo que le deja cerrar el bucle sin tocar el aparato: juzga la captura que le den, así
+     * que si el conductor fotografió el login, dictamina sobre el login. Pedir por nombre lo
+     * convierte en una delegación más —«ve a X y tráeme la foto»— en vez de en un agente con
+     * shell, que es lo que el invariante de «exactamente UN backend ejecutable» prohíbe.
+     *
+     * Vacía y nunca ausente: quien la lea no tiene que distinguir dos formas de «nada».
+     */
+    necesito: string[];
+}
+/**
+ * Lo que se le pide, y está escrito para que conteste lo que puede saber.
+ *
+ * «No digas la causa» no es modestia: es lo único que separa una observación útil —«el texto
+ * de los botones sale cortado»— de una pista falsa —«está rotado 180°»—, y lo segundo es lo
+ * que contestó las tres veces que se midió.
+ */
+export declare const PROMPT_VISUAL: string;
+/**
+ * Lo que se le pide CUANDO hay maqueta delante, y existe por una medida.
+ *
+ * **El modelo ve las imágenes de sobra; lo que decide qué ve es qué se le pide describir.**
+ * Sobre la calculadora de MyAllXOne el crítico acertó que una captura era el login y no la
+ * pantalla pedida, y leyó los rótulos `AP_EXPRESION`/`AP_RESULTADO` cortados contra el borde.
+ * Luego dio VERDE sobre una pantalla cuyas teclas eran rectángulos donde la maqueta tenía
+ * píldoras y cuyo resultado era 1,4 veces la expresión donde la maqueta pedía 2,7. No falló:
+ * `PROMPT_VISUAL` le dice literalmente que NO opine de la paleta ni de los gustos, y la
+ * fidelidad cae entera en ese conjunto excluido. La prueba de que era la pregunta y no la
+ * vista: el orquestador llegó a escribirle «las teclas llevan esquinas redondeadas (radio
+ * alto)» y el crítico no protestó, porque no se le pidió comparar.
+ *
+ * Tres cosas que no son de forma:
+ *
+ *  - **Se nombra QUÉ comparar** —proporciones, jerarquía de tamaños, forma y alineación— en
+ *    vez de pedir «¿se parecen?». Una pregunta abierta devuelve impresiones; ésta devuelve
+ *    sitios.
+ *  - **El COLOR se compara, el GUSTO no.** «El botón es coral donde la maqueta lo pone gris»
+ *    es un hecho comprobable contra una imagen que está delante; «la paleta es fría» sigue
+ *    siendo una opinión y sigue fuera. Sin referencia no se puede distinguir, y por eso allí
+ *    se excluyen los dos.
+ *  - **Se conserva «no diagnostiques la causa»**, que está medido seis veces: describe un
+ *    texto CORTADO como «girado 180°». Acierta DÓNDE y falla en el PORQUÉ, y eso no cambia
+ *    porque haya una maqueta al lado.
+ *
+ * Y se conserva que una diferencia deliberada no es un defecto: una plataforma no da todo lo
+ * que da un navegador, así que lo que se pide es lo que SE VE distinto, no un veredicto de
+ * si estuvo bien decidido.
+ */
+export declare const PROMPT_VISUAL_CON_REFERENCIA: string;
+export interface ContextoVisual {
+    /** Qué pantalla se supone que es. Va en el prompt para que no adivine dónde está. */
+    pantalla: string;
+}
+/**
+ * Le enseña la captura al modelo y devuelve su veredicto.
+ *
+ * `invocar` entra por parámetro, así que `npm test` no le pregunta a ningún modelo — el mismo
+ * molde que `JuezDeTareaPort`.
+ */
+export declare function juzgarPantalla(imagen: CapturaDePantalla, contexto: ContextoVisual, invocar: InvocarVisual, 
+/**
+ * La maqueta, si la hay. **Cuarto parámetro y opcional**, así los dos llamadores de
+ * `cli/` no cambian: lo que hace un `xonecode` de diagnóstico es mirar una pantalla, no
+ * compararla contra nada.
+ */
+referencia?: CapturaDePantalla, 
+/**
+ * HECHOS MEDIDOS de la geometría (`core/geometriaDePantalla.ts`): qué está tapado, qué falta, filas y
+ * tamaños, sacados del árbol de controles y no de mirar. Van en el prompt para que el modelo no tenga
+ * que adivinar la estructura —medido: no vio una «=» tapada y se inventó colores— y para que su
+ * texto no los contradiga. Él se queda con lo que solo se ve: formas, colores, jerarquía.
+ */
+hechos?: readonly string[]): Promise<VeredictoVisual>;
+/**
+ * Una pantalla DESCRITA (`core/descripcionDePantalla.ts`): el modelo mira UNA imagen sola y cuenta primero su
+ * geometría y después el estilo de cada control, con el mismo esquema para la maqueta y para la captura. A la
+ * captura se le pasan los controles que EXISTEN (`controlesQueExisten`, del árbol), para que no invente estructura.
+ *
+ * Se guarda por huella: cada ronda compara contra la MISMA descripción de la maqueta, no contra una nueva que varía.
+ * Lo que no se entiende es `undefined` (y no se guarda); no poder preguntar LANZA, como `juzgarPantalla`.
+ */
+export declare function describirPantalla(imagen: CapturaDePantalla, invocar: InvocarVisual, controlesQueExisten?: readonly string[]): Promise<PantallaDescrita | undefined>;
+/**
+ * El `invocar` de PRODUCCIÓN, sobre `ModelosPort`.
+ *
+ * La imagen viaja como un bloque `image_url` con un `data:` dentro de un `HumanMessage`, que
+ * es la forma multimodal que entienden los tres proveedores a través de langchain. Se mide
+ * aquí y no en el módulo puro porque esto toca el SDK.
+ *
+ * **La misma asimetría de `juezDeTarea#invocarConModelos`, y por la misma medida**: construir
+ * el modelo falla antes de tocar la red y con un mensaje escrito para leerse, así que ése se
+ * CONSERVA; de la llamada solo se conserva el NOMBRE del error, porque ahí los SDK devuelven
+ * el cuerpo remoto y con él cabeceras y claves redactadas.
+ */
+export declare function invocarVisualConModelos(modelos: {
+    paraPapel(papel: Papel): unknown;
+}): InvocarVisual;

package/dist/agent/dispositivos/lanzamientoEnMaquina.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Poner una app en el dispositivo y dejarla ARRANCADA: el recorrido entero, fase a fase.
+ *
+ * Es la mitad que EJECUTA lo que decide la pestaña «Ejecutar»: el túnel de `adb`, el ZIP del
+ * proyecto, la subida, el reinicio del framework y —por el canal de `/hotswap`— el lanzamiento
+ * con la lectura que dice si de verdad está viva.
+ *
+ * **Las fases, y por qué ese orden** (el de arriba abajo es el del código, y no es casual):
+ *
+ * 1. **`comprobando`.** El túnel PRIMERO, porque sin él el puerto local del aparato
+ *    (8443 por omisión, o el de su AVD) no lleva a ninguna parte: el servidor escucha en el `localhost` del aparato, y quien lo trae aquí es
+ *    `adb forward`. **Se aplica siempre y NO se quita al terminar**: se reaplica tras cada
+ *    reconexión del cable, así que quitarlo dejaría el SIGUIENTE lanzamiento hablando con
+ *    nadie. Y va antes de la comprobación del framework porque un aparato al que no se llega
+ *    falla aquí con la línea de `adb`, que es justo el diagnóstico de ese caso.
+ * 2. **`empaquetando`.** El ZIP, porque subir es lo que pone los ficheros nuevos en el
+ *    aparato. Es síncrono y en memoria: no hay fichero temporal.
+ * 3. **`subiendo`.** **Subir NO aplica**: el proceso del framework tiene cargado lo de antes,
+ *    y el ZIP no limpia el destino —añade y sobrescribe, así que los `-wal` de una base vieja
+ *    se quedan ahí—. Por eso no viaja `bd/`, y por eso esto no es el final del recorrido.
+ * 4. **`reiniciando`.** Es lo ÚNICO que aplica lo subido. Y es `SetupActivity`, **nunca
+ *    `.mainEntry`**: medido, `.mainEntry` no levanta el servidor.
+ * 5. **`lanzando`.** El lanzamiento por el WebSocket, esperando el saludo del servidor. Entra
+ *    por `deps.abrirSocket`, que es el CONSTRUCTOR del socket —así se llama en el módulo al que
+ *    alimenta—: el cliente de `/hotswap` ya está escrito y medido en `agent/dispositivos/hotswap.ts`, y `ws`
+ *    no se importa aquí.
+ * 6. **`comprobando-arranque`.** La LECTURA, porque `{"result":true}` de `launchApplication`
+ *    significa «aceptado», no «arrancó»: lo que dice si está viva es el árbol de controles.
+ *
+ * **El efecto de la subida va por `node:https`, y el porqué.** Ni `fetch` con un `dispatcher`
+ * de `undici` —`undici` no es dependencia de este repo— ni `NODE_TLS_REJECT_UNAUTHORIZED=0`,
+ * que desactivaría la confianza **para todo el proceso**, proveedores de modelo y CloudStudio
+ * incluidos: una variable de entorno no distingue a quién le estás hablando. `node:https` deja
+ * el `rejectUnauthorized` en ESTA petición (el certificado del aparato es autofirmado), deja
+ * poner `Content-Length` y manda el ZIP desde memoria, sin fichero temporal.
+ *
+ * **El silencio es el síntoma, no la lentitud** (`TOPE_SIN_SALIDA_MS`): `adb` contesta en
+ * milisegundos, y lo que no es normal es que se quede callado minutos. Con `TOPE_DE_TRABAJO_MS`
+ * por encima, para que un proceso que habla sin avanzar no se quede para siempre.
+ *
+ * **Se mata el GRUPO y no el hijo** (`detached: true` + `kill(-pid)`): medido, un nieto
+ * sobrevive a `child.kill()`.
+ *
+ * **Todos los efectos entran por `deps`.** `npm test` no lanza un `adb`, ni abre un socket, ni
+ * toca la red: el ZIP, la subida, el framework y el canal de `/hotswap` son puertos, y sus
+ * dobles viven en el test. El único `node:https` de verdad es el que se usa cuando nadie pasa
+ * un doble.
+ *
+ * **Y el 8443 DENTRO del aparato es el de FÁBRICA, no una garantía**: si está ocupado, el
+ * servidor coge el siguiente libre y el real se ve en la pantalla del framework. Esto se
+ * implementa contra 8443 dentro del aparato (el puerto LOCAL del túnel es el del AVD) y se anota; leer el puerto real no está implementado.
+ */
+import { type RequestOptions } from "node:https";
+import type { Dispositivo } from "../../core/dispositivos.js";
+import { type DependenciasDeDeteccion, type FrameworkEnDispositivo } from "./dispositivosEnMaquina.js";
+import { type AbrirSocketHotswap } from "./hotswap.js";
+import { TOPE_DE_TRABAJO_MS, TOPE_SIN_SALIDA_MS, type Lanzar } from "./procesosEnMaquina.js";
+import { type PaqueteDelProyecto } from "./paqueteDelProyecto.js";
+/**
+ * Los dos topes son los MISMOS de la instalación, y se reexportan desde aquí para que no haya
+ * una segunda copia de los números: son la misma regla —el silencio es el síntoma— sobre el
+ * mismo tipo de proceso. Viven con el ejecutor que los arma (`procesosEnMaquina.ts`), que es el
+ * que usan los dos módulos.
+ */
+export { TOPE_DE_TRABAJO_MS, TOPE_SIN_SALIDA_MS };
+/**
+ * Las fases del recorrido, en su orden. El tipo y la lista van juntos a propósito: quien pinte
+ * las fases (o el test que las exige en orden) tiene una sola definición que leer.
+ */
+export type FaseDeLanzamiento = "comprobando" | "empaquetando" | "subiendo" | "reiniciando" | "lanzando" | "comprobando-arranque";
+export declare const FASES_DE_LANZAMIENTO: readonly FaseDeLanzamiento[];
+/** Cómo acabó. `colgada` es «se quedó callado»: no es un fallo del proyecto ni del aparato. */
+export type EstadoDeLanzamiento = "ok" | "fallo" | "cancelada" | "colgada";
+/** Lo que hay que lanzar. Tres datos, y los tres son de la MEDIDA, no de una preferencia. */
+export interface PeticionDeLanzamiento {
+    /**
+     * El aparato. Su `id` es el serial de `adb` —el `-s` de cada comando— y su `plataforma`
+     * decide si esto puede empezar siquiera.
+     */
+    dispositivo: Dispositivo;
+    /** La raíz del proyecto: de ahí sale el ZIP. */
+    raiz: string;
+    /**
+     * El nombre de la app, el del `app.ini`. Va tal cual en `launchApplication` y escapado en la
+     * query de la subida: es el mismo dato en los dos sitios.
+     */
+    app: string;
+    /**
+     * El puerto LOCAL del túnel, el del AVD de este aparato (Ajustes → Dispositivos). Ausente,
+     * el de siempre. Dentro del aparato es siempre `PUERTO_DEL_HOTSWAP`.
+     */
+    puerto?: number;
+}
+/**
+ * La subida, vista por este módulo. Entra por parámetro porque `npm test` no puede abrir una
+ * conexión —ni contra un puerto que quizá no exista— y porque el cuerpo del cuerpo HTTP no es
+ * asunto de quien decide las fases.
+ */
+export interface PeticionDeSubida {
+    host: string;
+    puerto: number;
+    /** La ruta CON su query: `/file_upload?file=…&appName=…`. */
+    ruta: string;
+    metodo: "POST";
+    /** `Content-Length` va aquí dentro: sin ella el servidor contesta `411` y no lee nada. */
+    cabeceras: Record<string, string>;
+    /** El ZIP entero, en memoria. */
+    cuerpo: Uint8Array;
+}
+export interface RespuestaDeSubida {
+    /**
+     * El código HTTP, y nada más. **El cuerpo no se lee**: ninguna frase de este módulo lo lleva,
+     * porque lo que contesta un servidor puede traer de todo y una línea de log no es un volcado.
+     */
+    codigo: number;
+}
+/**
+ * Sube el paquete. La `senal` es la cancelación: una subida de 500 MB por un túnel lento es la
+ * fase más larga del recorrido, y un «Cancelar» que no corta hasta que acabe no es un cancelar.
+ */
+export type SubirPaquete = (peticion: PeticionDeSubida, senal?: AbortSignal) => Promise<RespuestaDeSubida>;
+export interface DependenciasDeLanzamiento {
+    /** De dónde se resuelve el `adb`, como en el resto del módulo de dispositivos. */
+    plataforma?: string;
+    entorno?: Record<string, string | undefined>;
+    home?: string;
+    existe?: (ruta: string) => boolean;
+    /** Cómo se lanza un proceso. Sin él, `spawn` con `detached: true` (ver `instalacionEnMaquina`). */
+    lanzar?: Lanzar;
+    /**
+     * Matar un GRUPO de procesos. Entra por parámetro porque el real es `process.kill(-pid)`, y
+     * un test que lo llamara de verdad mataría el grupo de quien corre `npm test`.
+     */
+    matarGrupo?: (pid: number, senal: string) => void;
+    frameworkEnDispositivo?: (dispositivo: Dispositivo, deps?: Pick<DependenciasDeDeteccion, "plataforma" | "entorno" | "home" | "existe" | "ejecutar">) => Promise<FrameworkEnDispositivo>;
+    empaquetarProyecto?: (raiz: string, tope?: number) => PaqueteDelProyecto;
+    subir?: SubirPaquete;
+    /**
+     * El constructor del socket de `/hotswap` — así se llama en `hotswap.ts`, que es el módulo al
+     * que alimenta—. Sin él se usa `ws`, y eso pasa DENTRO de `hotswap.ts`: aquí no se importa ni
+     * se abre ningún socket.
+     */
+    abrirSocket?: AbrirSocketHotswap;
+    /** Cada línea que merezca contarse, con la fase a la que pertenece. */
+    alFase?: (fase: FaseDeLanzamiento, linea: string) => void;
+    ahora?: () => number;
+}
+export interface ResultadoDeLanzamiento {
+    estado: EstadoDeLanzamiento;
+    /** La fase en la que acabó: la que falló, o la última si fue bien. */
+    fase: FaseDeLanzamiento;
+    /** UNA línea. Ausente si acabó bien o si lo canceló alguien. */
+    motivo?: string;
+    ms: number;
+}
+export interface LanzamientoEnCurso {
+    /** Corta lo que esté en vuelo: el proceso de `adb`, la subida y la espera del canal. */
+    cancelar: () => void;
+    terminado: Promise<ResultadoDeLanzamiento>;
+}
+/** El `200` es el único que no es un rechazo. Y un código que no está en la tabla se CUENTA. */
+export declare function motivoDeSubida(codigo: number): string | undefined;
+/**
+ * La ruta de la subida, con la query. `appName` va escapado: un nombre con un espacio, un `&`
+ * o un `#` partiría la query y el servidor leería otro nombre —o ninguno— sin decir nada.
+ */
+export declare function rutaDeSubida(app: string): string;
+/**
+ * Las cabeceras de la subida. `Content-Length` es obligatoria (sin ella: `411`).
+ *
+ * Y el `Content-Type` **está medido**, no supuesto: el comando que se midió funcionando la primera
+ * vez era un `curl --data-binary`, cuyo `Content-Type` por omisión es
+ * `application/x-www-form-urlencoded`, así que durante una pasada esto se declaró sin afirmarse.
+ * Ya se subió de verdad con `application/octet-stream` y el servidor contestó `200` **con los bytes
+ * enteros** — el `md5` de `LoginColl.xne` y de `app.xml` en el aparato coincide con el del proyecto
+ * en disco, y con eso subido la app arranca—, así que el cuerpo no se interpreta como formulario.
+ * Es lo correcto para bytes y es lo que vale; la medida entera está en `docs/DECISIONES.md`.
+ */
+export declare function cabecerasDeSubida(bytes: Uint8Array): Record<string, string>;
+/**
+ * Las opciones de la petición, en UNA función que se puede mirar sin abrir nada.
+ *
+ * Existe para que la decisión de TLS y de método sea comprobable: `rejectUnauthorized: false`
+ * es el certificado autofirmado del aparato, y el destino es un túnel de `adb` en loopback.
+ * Un test que hablara con un servidor de verdad para comprobarlo necesitaría red y un
+ * certificado; esto se lee.
+ */
+export declare function opcionesDeSubida(peticion: PeticionDeSubida, senal?: AbortSignal): RequestOptions;
+/**
+ * El recorrido entero, lanzado. Devuelve el trabajo en curso: se puede cancelar mientras corre.
+ *
+ * **Nunca lanza.** Todo lo que puede ir mal —no hay `adb`, no hay framework, el paquete no se
+ * puede montar, el servidor contesta un código, el proceso se queda callado— vuelve como un
+ * `ResultadoDeLanzamiento` con su fase y su línea de motivo: quien llama está atendiendo una
+ * petición del navegador y un aparato que no contesta no es una excepción del programa.
+ */
+export declare function lanzarEnDispositivo(peticion: PeticionDeLanzamiento, deps?: DependenciasDeLanzamiento): LanzamientoEnCurso;

package/dist/agent/dispositivos/paqueteDelProyecto.d.ts

@@ -0,0 +1,28 @@
+/** Bytes a partir de los cuales el endpoint contesta `413` y no se sube nada. */
+export declare const TOPE_DE_PAQUETE: number;
+export interface PaqueteDelProyecto {
+    /** El ZIP entero, en memoria: es el cuerpo de la subida. */
+    bytes: Uint8Array;
+    /** Lo que entró, relativo a la raíz, en POSIX y ordenado. */
+    ficheros: string[];
+    /**
+     * Lo que SUMAN los ficheros que entraron, en disco: es la cifra que vigila el tope y la
+     * que tiene sentido enseñar junto a la lista. No es `bytes.length` — el ZIP pesa menos
+     * que su contenido, y cuánto menos depende de lo que ya venía comprimido.
+     */
+    total: number;
+}
+/**
+ * Un tamaño en MB con un decimal y en coma: es una cifra que lee una persona.
+ *
+ * Se EXPORTA porque la línea del recorrido de lanzamiento enseña los mismos tamaños
+ * (`lanzamientoEnMaquina.ts`): un segundo formateador allí diría `12.3 MB` donde aquí se dice
+ * `12,3 MB`, y dos formatos para la misma cifra enseñan a desconfiar de los dos.
+ */
+export declare function enMegas(bytes: number): string;
+/**
+ * Los bytes del paquete. El `tope` entra por parámetro para poder probar el rechazo sin
+ * fabricar medio giga —el mismo recurso que el reloj de `MS_ENTRE_PARCIALES`—: un tope
+ * que solo se puede ejercitar con 512 MB de verdad es un tope que nadie prueba.
+ */
+export declare function empaquetarProyecto(raiz: string, tope?: number): PaqueteDelProyecto;

package/dist/agent/dispositivos/procesosEnMaquina.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Cuánto se aguanta SIN una sola línea de salida antes de darlo por colgado.
+ *
+ * No es un tope de duración: `sdkmanager` habla mientras descarga (porcentajes) y `adb`
+ * contesta en milisegundos, así que mientras diga algo se le espera lo que haga falta — una
+ * descarga de 3 GB por una línea lenta puede tardar media hora, y matarla por ser lenta sería
+ * peor que esperarla. Lo que no es normal es el SILENCIO: eso es un prompt esperando a alguien
+ * que no está.
+ */
+export declare const TOPE_SIN_SALIDA_MS: number;
+/** Y un tope total, para que un proceso que habla sin avanzar no se quede para siempre. */
+export declare const TOPE_DE_TRABAJO_MS: number;
+/** El hijo, visto por este módulo. Entra por parámetro para poder probarlo sin lanzar nada. */
+export interface ProcesoHijo {
+    stdout: {
+        on: (evento: "data", cb: (dato: unknown) => void) => void;
+    };
+    stderr: {
+        on: (evento: "data", cb: (dato: unknown) => void) => void;
+    };
+    stdin: {
+        write: (texto: string) => void;
+        end: () => void;
+    };
+    on: (evento: "close" | "error", cb: (valor: never) => void) => void;
+    kill: (senal?: string) => boolean;
+    /**
+     * Con `detached` el hijo es LÍDER de su grupo, y su pid es el del grupo. Es lo que
+     * permite matar también a los nietos; ausente, se cae a matar solo al hijo.
+     */
+    pid?: number;
+}
+export type Lanzar = (binario: string, args: string[], opciones: {
+    env: Record<string, string | undefined>;
+}) => ProcesoHijo;
+/**
+ * Por qué se dio por colgado. Se devuelve como CAUSA y no como frase: cada módulo escribe la
+ * suya, porque el silencio y las vueltas no son el mismo hecho.
+ */
+export type CausaDelCuelgue = "silencio" | "total";
+/**
+ * En qué acabó un proceso.
+ *
+ * Es una unión discriminada y no un `motivo?` suelto a propósito: un `fallo` SIEMPRE trae su
+ * línea —es lo único que hay que enseñar—, y un `colgada` trae su causa pero no su frase, que
+ * la pone quien llama. Así el tipo no deja escribir un fallo mudo ni un cuelgue ya redactado.
+ */
+export type FinDeProceso = {
+    estado: "ok";
+} | {
+    estado: "cancelada";
+} | {
+    estado: "fallo";
+    motivo: string;
+} | {
+    estado: "colgada";
+    cuelgue: CausaDelCuelgue;
+};
+export interface OpcionesDeUnaEjecucion {
+    /** El entorno del hijo. Sin él, el del ejecutor. */
+    env?: Record<string, string | undefined>;
+    /** Lo que se le escribe por `stdin`; sin TTY, un prompt sin respuesta cuelga el proceso. */
+    teclear?: readonly string[];
+    /** Cuántas veces se repite el tecleo. Las licencias del SDK son una pregunta por licencia. */
+    repetir?: number;
+    /** Cada línea de salida, ya partida y sin el salto, en cuanto sale. */
+    alSalirLinea?: (linea: string) => void;
+}
+export interface Ejecutor {
+    /**
+     * Corre un proceso y espera a que acabe. **Uno a la vez**: el que esté en vuelo es al que
+     * cancela `cancelar()`, que es como lo usan los dos módulos —una receta encadena procesos,
+     * y un lanzamiento también.
+     */
+    correr: (binario: string, args: string[], opciones?: OpcionesDeUnaEjecucion) => Promise<FinDeProceso>;
+    /**
+     * Mata al que esté en vuelo, con `SIGTERM`, y lo deja cancelado: lo que se pida después no
+     * llega a arrancar. Es pegajoso a propósito — cancelar durante un paso de dos procesos no
+     * puede dejar el segundo corriendo.
+     */
+    cancelar: () => void;
+}
+export interface DependenciasDeProcesos {
+    lanzar?: Lanzar;
+    /**
+     * Matar un GRUPO de procesos. Entra por parámetro porque el real es `process.kill(-pid)`, y
+     * un test que lo llamara de verdad mataría el grupo de quien corre `npm test`.
+     */
+    matarGrupo?: (pid: number, senal: string) => void;
+    /** El entorno del hijo, cuando quien llama no trae el suyo. */
+    entorno?: Record<string, string | undefined>;
+}
+/**
+ * Mata un árbol de procesos por PID, en las DOS plataformas. Es la ÚNICA función que decide
+ * CUÁNDO y CÓMO se mata un árbol — la comparte `agent/grafo/ejecucionCancelable.ts`.
+ *
+ * En Windows no hay grupos de proceso POSIX ni `SIGTERM`/`SIGKILL` de verdad: `taskkill /T`
+ * recorre el árbol real por PID (no depende de `detached`) y `/F` es el único modo forzoso
+ * que hay — no existe un equivalente "amable".
+ *
+ * `plataforma`/`taskkill` inyectables por lo de siempre: un test en macOS/Linux no puede
+ * ejecutar `taskkill` de verdad, pero sí puede comprobar que se construye la invocación
+ * correcta.
+ */
+export declare function matarGrupoReal(pid: number, senal: string, opciones?: {
+    plataforma?: NodeJS.Platform;
+    taskkill?: (args: string[]) => void;
+}): void;
+/** Un ejecutor con los efectos que le pasen. Sin nada, los de verdad. */
+export declare function crearEjecutor(deps?: DependenciasDeProcesos): Ejecutor;
+/**
+ * Una línea, nunca la salida entera ni una traza con rutas.
+ *
+ * Es la de un proceso: `ENOENT` tiene frase propia porque «el ejecutable no existe» es lo que
+ * hay que leer, y el resto se corta en la primera línea. Un canal de RED pone su caso encima y
+ * cae aquí para lo demás (`lanzamientoEnMaquina.ts`), que es como se evita tener dos copias
+ * que ya divergieron una vez.
+ */
+export declare function unaLinea(error: unknown): string;
+/**
+ * El motivo de un código distinto de cero. La última línea si dijo algo, y si no el código
+ * — que es todo lo que hay.
+ */
+export declare function motivoDelCodigo(codigo: number | null, ultima: string): string;
+/**
+ * `sdkmanager`/`avdmanager` son `.bat` en Windows (`localizadorDeAndroid` ya lo sabe, ver
+ * `extensionDeBinario`), y desde que Node cerró el CVE-2024-27980 —la inyección de comandos
+ * por `.bat`/`.cmd`— un `spawn` a secas sobre uno de estos revienta con `spawn EINVAL` en
+ * vez de arrancar: medido en la máquina del usuario, «No salió bien: spawn EINVAL» al pulsar
+ * el paso 4 de la receta de Windows. La forma sancionada por Node de arreglarlo es `shell:
+ * true`, y aquí es seguro dárselo —a diferencia del caso general que el CVE cerraba—: los
+ * `args` de estos dos binarios NUNCA llevan nada que no sea un literal de nuestra propia
+ * tabla (`PASOS_EJECUTABLES`), nunca una cadena que haya escrito un usuario.
+ */
+export declare function necesitaShell(binario: string, plataforma?: string): boolean;
+/**
+ * El hijo de verdad. Dos decisiones, las dos medidas:
+ *
+ * - **`detached: true`**, para que sea líder de su grupo y `kill(-pid)` se lleve también a
+ *   los nietos: sin ello, cancelar dejaba el `curl` de `brew` descargando.
+ * - **`stdio[0]` sigue siendo un `pipe`**, porque `sdkmanager` necesita que se le teclee.
+ *   Lo que hace que un `sudo` de dentro no cuelgue no es cerrar `stdin`: es no tener
+ *   terminal de CONTROL, que es de donde `sudo` lee la contraseña — y con `detached` no lo
+ *   tiene ni por herencia.
+ * - **`shell: true` SOLO para `.bat`/`.cmd`** (`necesitaShell`, arriba): para `adb`/`emulator`
+ *   y para `brew` —los binarios que lanza el resto de este módulo, incluido el lanzamiento en
+ *   el dispositivo— nada cambia, exactamente el mismo `spawn` de siempre.
+ *
+ * Es el valor POR OMISIÓN de `crearEjecutor`, y el único `spawn` de los dos módulos: la receta
+ * de instalación y el `adb` del lanzamiento necesitan exactamente estas dos cosas por los
+ * mismos motivos, y un segundo `spawn` sería un segundo sitio donde el `detached` puede dejar
+ * de estar —y ese día el `kill(-pid)` de un sitio mataría a un grupo que no existe—.
+ */
+export declare const lanzarReal: Lanzar;

package/dist/agent/dispositivos/recargaEnAparato.d.ts

@@ -0,0 +1,30 @@
+import { type ResultadoDeRecarga } from "../../core/recargaEnCaliente.js";
+import { type AbrirSocketHotswap } from "./hotswap.js";
+export interface PeticionDeRecarga {
+    /** El serial de adb del aparato de la sesión. */
+    serie: string;
+    /** El puerto LOCAL del túnel: el del AVD, o el de fábrica para un físico. */
+    puerto: number;
+    /** El nombre de la app, el MISMO que usa Ejecutar (`puedeLanzarse`). */
+    app: string;
+    /** La ruta relativa al proyecto, con `/`. */
+    ruta: string;
+    /** Los bytes del fichero TAL CUAL están en disco: su codificación decide cómo se le dice. */
+    bytes: Uint8Array;
+}
+export interface DependenciasDeRecarga {
+    /** Aplicar el túnel. Devuelve el motivo si falló, `undefined` si quedó puesto. */
+    aplicarTunel?: (serie: string, puerto: number) => Promise<string | undefined>;
+    abrirSocket?: AbrirSocketHotswap;
+}
+/** Lleva el fichero al aparato y lo aplica. Nunca lanza. */
+export declare function recargarEnAparato(peticion: PeticionDeRecarga, deps?: DependenciasDeRecarga): Promise<ResultadoDeRecarga>;
+/** A qué aparato y app va una recarga: lo resuelve el servidor, no el cliente. */
+export type DestinoDeRecarga = Pick<PeticionDeRecarga, "serie" | "puerto" | "app">;
+/**
+ * Lee el fichero del proyecto con las MISMAS guardas que el lector de Ficheros
+ * (`resolverEnProyecto`: texto y `realpath`) y lo recarga. Lo que no se deja leer no viaja.
+ */
+export declare function recargarFicheroDelProyecto(raiz: string, ruta: string, destino: DestinoDeRecarga, deps?: DependenciasDeRecarga): Promise<ResultadoDeRecarga>;
+/** Relanzar la app, a petición de la persona. Nunca lanza. */
+export declare function relanzarEnAparato(peticion: Pick<PeticionDeRecarga, "serie" | "puerto" | "app">, deps?: DependenciasDeRecarga): Promise<ResultadoDeRecarga>;

package/dist/agent/dispositivos/sensorDeArranque.d.ts

@@ -0,0 +1,42 @@
+import type { InformeVerificacion } from "../../core/ports.js";
+/** No se pudo PREGUNTARLE al aparato. Entorno, no proyecto. */
+export declare class ErrorDelAparato extends Error {
+    constructor(motivo: string);
+}
+export interface DependenciasDelSensor {
+    /** ¿Hay algún aparato conectado? */
+    hayAparato: () => Promise<boolean>;
+    /** Vacía el buffer del log. */
+    limpiarLog: () => Promise<void>;
+    /** Pone el proyecto en el aparato y deja la app arrancada. */
+    desplegar: (raiz: string) => Promise<{
+        ok: boolean;
+        detalle: string;
+    }>;
+    /** El log del host tras el arranque. */
+    leerLog: () => Promise<string>;
+}
+/**
+ * Despliega y devuelve lo que el aparato dijo, en la forma que el bucle ya consume.
+ *
+ * **Verde es que no hay hallazgos DE LA APP.** Lo de la plataforma viaja en el informe —no se
+ * tira nunca, ver `core/logDeDispositivo.ts`— pero como `warning`, así que no pinta el turno
+ * de rojo: son quejas de Android sobre sí mismo y nadie las puede arreglar desde un `.xne`.
+ */
+export declare function arranqueEnDispositivo(raiz: string, deps: DependenciasDelSensor): Promise<InformeVerificacion>;
+/**
+ * Cuánto se le da al despliegue. El script hace la cadena entera —túnel, ZIP, subida,
+ * reinicio, lanzamiento y comprobación de que la app está VIVA— y sobre un `pixel8` en
+ * caliente tardó 5 s con un proyecto de 6,8 MB. El tope es para el caso frío con un proyecto
+ * grande, y por debajo del tope de reloj de un comando del harness.
+ */
+export declare const TOPE_DE_DESPLIEGUE_MS = 300000;
+/**
+ * El sensor de verdad: `adb` para el log y el script de la skill para el despliegue.
+ *
+ * **El despliegue NO se reimplementa aquí.** `xone-desplegar-android` ya es la cadena medida
+ * —y la única que sabe que hay que reiniciar con `SetupActivity` y no con `.mainEntry`, y que
+ * el ZIP va sin `.xonecode`—. Reescribirla sería un segundo sitio donde esa secuencia puede
+ * divergir, que es como este repo se ha roto siempre.
+ */
+export declare function sensorDeArranqueReal(): DependenciasDelSensor;