xonecode 0.38.44 → 0.39.2

package/dist/core/entrega.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Cuándo una tarea está TERMINADA: las condiciones que comprueba el código, más el
+ * veredicto de un juez, y por qué ninguna de las dos mitades basta sola.
+ *
+ * `core/`, o sea datos y reglas puras: ni disco, ni git, ni modelos. Quien MIDE es el
+ * corredor (`web/servidor/corredorDeTareas.ts`); aquí solo se decide con lo medido.
+ *
+ * **Por qué el veredicto del juez no basta solo.** Es la regla que este repo ya tenía
+ * escrita, palabra por palabra, para la subida autónoma
+ * (`core/cloudstudio.ts#PoliticaDeAprobacion`): «el veredicto del juez no bastará solo:
+ * exigirá además condiciones que comprueba el código (verificador en verde, árbol limpio,
+ * nada pendiente de aprobar), porque en este repo los avisos son código y no prompt
+ * precisamente porque a un modelo se le puede pedir que avise y no avisa». Este fichero es
+ * esa frase hecha código. Si el juez pudiera entregar solo, «terminada» valdría lo que
+ * valga la buena voluntad de un modelo esa vez.
+ *
+ * **Y por qué las condiciones tampoco bastan solas**: las tres son propiedades del
+ * PROCESO —se escribió, se midió, se puede revisar—, y ninguna dice si lo escrito es lo
+ * que se pedía. Eso es lo único que aporta el juez, y es también lo único que se le
+ * pregunta.
+ *
+ * **La tercera condición NO es «árbol de git limpio», y eso está MEDIDO.** El plan la
+ * escribía como `arbolSucio: false`, con `arbolLimpio` (`agent/sesiones/gitSync.ts`) detrás. Medido
+ * sobre un repo de verdad: una tarea que escribe UN fichero deja `git status --porcelain`
+ * con `?? Clientes.xne`, o sea `arbolLimpio === false` — el árbol de una tarea que ha
+ * trabajado está sucio POR DEFINICIÓN, así que con esa condición NINGUNA tarea se
+ * entregaría nunca. Lo que hay que exigir es otra cosa, y es la que el §0 del diseño
+ * nombra: «sin aprobación previa, la revisión posterior es la única forma de mirar». O
+ * sea, que lo que la tarea escribió se pueda REVISAR — que exista la marca de git de su
+ * sesión y el diff salga (`agent/sesiones/sesionGit.ts#cambiosDeSesion` con `via: "git"`, la misma
+ * función que pinta la pestaña Revisión, no una parecida). Un campo llamado `arbolSucio`
+ * que midiera eso sería la misma clase de mentira que `aplicados` habría sido para
+ * `Tarea.autorizadas`, así que se llama `revisable`.
+ */
+import type { HallazgoDelTurno } from "./events.js";
+/**
+ * Cómo acabó el verificador en el turno, con TRES valores y no un booleano.
+ *
+ * Por la misma razón que los estados de una herramienta en `dispositivos.ts`: «no se
+ * sabe» no es «está bien». Un turno que no escribió no corre el simulador, otro no lo
+ * encuentra en el PATH y otro se cortó antes de llegar — y ninguno de los tres es verde.
+ */
+export type EstadoDeVerificador = "verde" | "rojo" | "no-corrio";
+/**
+ * Lo que el simulador NO comprueba: documentación. Un `.md` no es parte de la app XOne y `xone-simulator validate`
+ * mira la app, así que verificar un turno que solo dejó documentación ni dice nada de lo escrito ni puede fallar por
+ * ello — y sin el binario en la máquina tumbaba un turno que había escrito bien (IXCODE-27). LISTA BLANCA y corta a
+ * propósito: lo que no esté aquí se sigue verificando, que es el lado seguro.
+ */
+export declare const EXTENSIONES_DE_DOCUMENTACION: ReadonlySet<string>;
+/** ¿Son TODAS las rutas documentación? Con alguna ruta: una lista vacía no es «solo documentación», es nada. */
+export declare function soloDocumentacion(rutas: readonly string[]): boolean;
+/**
+ * Lo que un TURNO puede decir de sí mismo, y que hasta ahora se tiraba.
+ *
+ * **Este tipo existe por una deuda medida.** `EjecutorDeTurno` devolvía `Promise<void>` y
+ * `crearEjecutorReal` (`cli/main.ts`) descartaba el retorno de `sesion.turno`, así que el
+ * `cortadoPorTope` que sabe que quedaron escrituras sin aplicar no salía de ahí. Medido
+ * con las tareas autónomas: cuatro ficheros escritos, una escritura abandonada al agotarse
+ * el tope de rondas, el verificador sin correr ni una vez, y el kanban diciendo
+ * «terminada». Sin abrir este canal, la condición `pendientes: 0` no tiene con qué
+ * medirse.
+ *
+ * Nada de aquí lleva contenido de ficheros: el estado del verificador, cuántas escrituras
+ * quedaron colgando, y los hallazgos en la misma forma que ya viaja en el evento
+ * `verificacion` —código, severidad, mensaje, fichero RELATIVO y línea—.
+ */
+/** Cuánto de la pregunta entra en el motivo: se pinta en el kanban, y la pregunta entera se ve en su chat. */
+export declare const TOPE_DE_PREGUNTA_EN_EL_MOTIVO = 300;
+/** El motivo de una tarea aparcada porque el agente pregunta. Se contesta con el feedback de la tarea. */
+export declare function motivoDePreguntaPendiente(pregunta: string): string;
+export interface ResultadoDeTurno {
+    verificador: EstadoDeVerificador;
+    /**
+     * Escrituras que quedaron esperando aprobación y **no se aplicaron**.
+     *
+     * Se mide al final del turno y no se deduce de `cortadoPorTope`: por ahí se sale por
+     * tres puertas distintas (el tope de rondas, el tope de tandas automáticas y «no hay
+     * quién apruebe») y las tres dejan escrituras colgando. El número es lo accionable.
+     */
+    pendientes: number;
+    /**
+     * El tope de rondas de escritura que el turno AGOTÓ, si se cortó por eso. Ausente = no se cortó por el tope (o el
+     * motor no lo dice). Con él, el motivo dice la verdad: «agotó el tope de N rondas», no «quedaron escrituras esperando
+     * aprobación», que en una tarea —sin nadie a quien preguntar— hacía pensar que faltaba aprobar algo.
+     */
+    topeAgotado?: number;
+    /**
+     * El turno acabó con una pregunta del agente en espera (TrueForge, `ask_user_question`): su enunciado. Un turno así
+     * acaba «limpio», pero no ha terminado nada —espera una respuesta—, así que no pasa por la entrega: se aparca con la
+     * pregunta (`motivoDePreguntaPendiente`). Medido en Maset: pasaba por el juez, que dictaba «la sesión no escribió
+     * ningún fichero», y ese rojo se quedaba en la tarea mientras trabajaba después. Ausente = no quedó ninguna.
+     */
+    preguntaPendiente?: string;
+    /**
+     * Lo BLOQUEANTE medido por el crítico visual en su ÚLTIMA crítica del turno (el estado final de la pantalla): un
+     * control tapado, fuera de la pantalla o que falta respecto a la maqueta. Es CRÍTICO para el cierre (`## CRITICAL`);
+     * un defecto de detalle no. Ausente = no hubo crítica, o no dio nada bloqueante.
+     */
+    bloqueantesVisuales?: string[];
+    /**
+     * Bloqueantes visuales que el agente EXPLICA en su respuesta final (los nombra: los decidió no hacer, o dice por qué
+     * no pudo). No son críticos: van como observaciones (`omisionDeclarada`). Medido en Maset: «Turno de Día», los
+     * contadores y la quinta tarjeta salían en `## CRITICAL` estando en su apartado de decisiones.
+     */
+    omisionesExplicadas?: string[];
+    /**
+     * Bloqueantes de una crítica ANTERIOR a los últimos cambios del proyecto: no describen la pantalla final, así que no son
+     * críticos —se dicen como observación, sin comprobar—. Medido en Maset: el desarrollador cambió la pantalla tras la
+     * última crítica y el cierre puso en `## CRITICAL` lo que esa crítica había visto antes.
+     */
+    bloqueantesDesfasados?: string[];
+    /**
+     * Pantallas de Stitch que el turno pidió por título y no existen (ni casan por palabras). CRÍTICO, decisión suya:
+     * medido en Maset, «Menu Listado Entregas» no estaba y la tarea construyó la ventana con otra maqueta.
+     */
+    pantallasNoEncontradas?: string[];
+    /**
+     * Las comprobaciones VISUALES del turno, una línea cada una y medidas por el harness: lo que dio cada
+     * `comparar_capturas` y `xone_critica_visual`, y el crítico de pantalla del cierre. Van al juez de QA como HECHO:
+     * medido en una tarea real (Maset), el juez dictó rojo porque «no consta la validación visual» que el criterio pedía,
+     * con seis comparaciones y seis críticas hechas en ese turno — no recibía nada de eso. Ausente = no hubo ninguna.
+     */
+    comprobacionesVisuales?: string[];
+    /**
+     * Los hallazgos del turno, si el verificador corrió. Es lo que el informe del verificador
+     * ya declara que viaja «al ejecutor como brief, al juez como hecho»
+     * (`core/ports.ts#InformeVerificacion`).
+     */
+    hallazgos?: HallazgoDelTurno[];
+    /**
+     * Cuántos hallazgos del simulador quedaron FUERA del reparto: los que caen en ficheros
+     * que este turno no tocó. El otro lado de `hallazgos`, y hasta ahora solo se pintaba en
+     * la consola (evento `verificacion`) y se tiraba.
+     *
+     * **Viaja porque el juez de QA lo necesita para no acusar al agente de lo que no hizo.**
+     * `hallazgos` ya está filtrada por el reparto de `agent/turno/turnoReal.ts#conVerificacion`,
+     * pero quien la recibe no puede saber que lo está: en la primera ejecución real del juez
+     * eso acabó en un rojo que decía que el turno había modificado los ficheros de los que
+     * hablaban los hallazgos. Con este número, la lista se lee por lo que es.
+     *
+     * **Ausente y CERO no son lo mismo**, como siempre por aquí: `0` es «el verificador
+     * corrió y no había ningún otro», y ausente es «no se midió» — el turno que no escribió,
+     * el que no tiene simulador, el que se cortó antes. El evento lo omite en cero porque
+     * ahí es una línea de consola que no diría nada; esto es un dato, y cero es un dato.
+     */
+    preexistentes?: number;
+    /**
+     * Por qué NO corrió, cuando se sabe: el binario que falta, o que esta ejecución no
+     * tiene verificador. Ausente con `no-corrio` significa que el turno no llegó a
+     * intentarlo — casi siempre porque no escribió nada, o porque se cortó antes.
+     */
+    motivoSinVerificar?: string;
+    /**
+     * El texto de las notas (IXCODE-4) que nadie llegó a recibir antes de que el turno cerrara,
+     * concatenado. Quien orquesta las sesiones (`vestibulo.ts`) decide con esto si dispara el
+     * turno siguiente — este tipo solo REPORTA, no dispara nada.
+     */
+    notasSobrantes?: string;
+}
+/** Lo del turno más lo que solo se puede medir desde fuera. */
+export interface MedidaDeEntrega extends ResultadoDeTurno {
+    /**
+     * ¿Se puede REVISAR lo que la tarea escribió? O sea: existe la marca de git de su sesión
+     * y el diff sale (`cambiosDeSesion(...).via === "git"`).
+     *
+     * No es «el árbol está limpio» (ver la cabecera): es que lo escrito sea visible. Sin
+     * aprobación previa, ese diff es el ÚNICO momento en que una persona puede mirar lo que
+     * hizo una tarea; entregar trabajo que nadie puede ver sería exactamente el sitio vacío
+     * que el modal de aprobación dejó.
+     */
+    revisable: boolean;
+    /**
+     * ¿Cambió la sesión algún fichero, **SEGÚN GIT**? `undefined` = no se sabe.
+     *
+     * De aquí depende que una tarea de SOLO LECTURA se pueda entregar, y la fuente importa:
+     * lo dice `cambiosDeSesion` —la misma que `revisable`— y **nunca `autorizadas`**. Aquello
+     * es una pista de lo que el agente quiso escribir, y puede llevar rutas que las guardas
+     * rechazaron; decidir con ella sería decidir con la intención en vez de con el hecho.
+     *
+     * Solo se puede afirmar cuando hay marca (`via: "git"`): sin ella no es que no escribiera,
+     * es que no hay con qué mirarlo — y entonces esto queda `undefined` y la condición del
+     * verificador se exige como siempre. Es la distinción de siempre entre «ninguno» y «no se
+     * sabe», y aquí colapsarla sería un camino para entregar sin verificar.
+     */
+    escribio?: boolean;
+    /**
+     * QUÉ cambió, según git: las rutas RELATIVAS del mismo diff del que sale `escribio`
+     * (`corredorDeTareas.ts#revisionConGit`, una sola medida para las dos cosas, así que no
+     * pueden discrepar). De aquí sale el HECHO que se le cuenta al juez de QA.
+     *
+     * **Existe porque `autorizadas` no puede hacer este trabajo.** Aquello se apunta al
+     * autorizar la escritura y es la intención del agente; esto es un diff contra el «antes»
+     * de la sesión. Todo el modo de fallo medido del juez era «no puedo comprobar la
+     * existencia ni el contenido de X»: darle el hecho fichero a fichero lo quita de raíz, y
+     * de paso le deja juzgar la cobertura del encargo ruta por ruta.
+     *
+     * **Ausente y VACÍA no son lo mismo**: ausente es «no se pudo preguntar a git» —sin marca
+     * no hay con qué comparar— y `[]` es «git dice que no cambió nada». Colapsarlas haría que
+     * un proyecto sin marca pareciera un proyecto intacto.
+     */
+    cambiados?: readonly string[];
+    /**
+     * Cuántas escrituras AUTORIZÓ el turno (`Tarea.autorizadas`), si consta.
+     *
+     * No es del turno ni de git: es de la tarea, y entra por su propio parámetro. Está aquí
+     * para una sola condición —autorizó escrituras y git no ve ni un cambio—, y **ausente es
+     * «no consta»**: una tarea de antes de que esto existiera, o un ejecutor que no lo informa.
+     * Acusar con un dato que no se tiene es exactamente lo que estas condiciones no hacen.
+     */
+    autorizadas?: number;
+}
+/** El veredicto de un juez de QA. Texto para leer y hallazgos, nunca contenido de ficheros. */
+export interface VeredictoDeTarea {
+    /** `indeterminado` = no se entendió lo que contestó. No es verde. */
+    veredicto: "verde" | "rojo" | "indeterminado";
+    /** Una o dos frases. Es lo que una persona lee en la tarjeta. */
+    resumen: string;
+    /** Lo que le falta o le sobra, una frase por hallazgo. */
+    hallazgos?: string[];
+    /**
+     * Con qué condición de MENOS se entregó. **Lo pone el CÓDIGO, no el juez**, y viaja aquí
+     * porque el `motivo` de una tarea terminada no existe (`conEstado` lo borra a propósito:
+     * «el motivo vive SOLO en el estado que lo explica») y este es el único sitio que
+     * sobrevive a una entrega.
+     *
+     * Hoy son `SALVEDAD_SIN_ESCRITURAS` y `SALVEDAD_SOLO_DOCUMENTACION`. Una entrega con una condición menos no puede
+     * parecer una entrega normal — y eso solo es cierto porque este campo VIAJA: el veredicto
+     * entero sale por el cable (`web/servidor/transporte.ts#filaDeTarea`) y lo pinta
+     * `apps/web/src/componentes/EntregaDeTarea.tsx`. Estuvo un tiempo sin cablearse, y
+     * entonces esta frase era falsa en la única pantalla donde importa.
+     */
+    salvedad?: string;
+}
+/** ¿Se entrega? Y si no, POR QUÉ — que es lo único accionable de una tarjeta aparcada. */
+export interface Entrega {
+    entregable: boolean;
+    motivo?: string;
+    /**
+     * Con qué condición de MENOS se entregó, cuando fue el caso. Texto para leer.
+     *
+     * Una entrega con una condición menos no puede parecer una entrega normal: hoy la única
+     * es la tarea que no escribió nada, donde el verificador no aplica y el veredicto del
+     * juez queda como la única condición de contenido. Quien lo lea tiene derecho a saberlo.
+     */
+    salvedad?: string;
+    /**
+     * Lo CRÍTICO, aparte de si se entrega: una tarea cortada (el tope de rondas), que no llegó a escribir lo que autorizó,
+     * o con un bloqueante visual medido. Decisión suya: una tarea que se completó con problemas o detalles (un rojo del
+     * juez, errores del verificador) NO es crítica. Va bajo `## CRITICAL` en el comentario de cierre. Ausente = nada.
+     */
+    criticos?: string[];
+    /** Lo que falló y NO es crítico (verificador, juez, marca de git…): observaciones del cierre. Ausente = nada. */
+    observaciones?: string[];
+}
+/**
+ * La medida a partir de lo que el turno informó. **Ausente no es vacío.**
+ *
+ * Un ejecutor que no informa —el guionizado, o una piel que no reenvíe el retorno— no ha
+ * dicho que el verificador esté verde: ha dicho nada. Darlo por verde sería la entrega
+ * silenciosa que todo esto existe para impedir, así que se traduce a `no-corrio` DICIENDO
+ * que nadie informó, que es otra cosa que «el simulador no está».
+ */
+export declare function medidaDeEntrega(resultado: ResultadoDeTurno | undefined, 
+/** Lo que dice git de la sesión. `escribio` y `cambiados` solo se afirman con marca: ver
+ *  los campos. Ausente no se rellena con nada, en las dos. */
+revision: {
+    revisable: boolean;
+    escribio?: boolean;
+    cambiados?: readonly string[];
+}, 
+/** Cuántas escrituras autorizó el turno, si consta. Ver `MedidaDeEntrega.autorizadas`. */
+autorizadas?: number): MedidaDeEntrega;
+/**
+ * Lo que se dice de una entrega a la que le faltó una condición porque no APLICABA.
+ *
+ * Se exporta para que quien la lea (y quien la pruebe) no la reescriba a mano.
+ */
+export declare const SALVEDAD_SIN_ESCRITURAS: string;
+export declare const SALVEDAD_SOLO_DOCUMENTACION: string;
+/**
+ * Las tres condiciones que comprueba el CÓDIGO. Pura.
+ *
+ * El motivo nombra TODAS las que fallaron y no la primera: es el caso medido de la deuda
+ * que esta pieza hereda —un turno cortado por el tope tiene escrituras pendientes Y un
+ * verificador que no corrió—, y decir solo una de las dos manda a adivinar la otra. Es la
+ * misma regla del aviso de honestidad que saca los NOMBRES de los ficheros en vez de un
+ * contador.
+ */
+export declare function condicionesDeEntrega(medida: MedidaDeEntrega): Entrega;
+/**
+ * La decisión final: las condiciones Y el juez.
+ *
+ * El orden importa y es el de siempre, fail-closed: si una condición falla, el veredicto
+ * del juez no se mira siquiera — su motivo sería ruido sobre un hecho. Quien llama puede
+ * además preguntar primero por `condicionesDeEntrega` para no gastar una llamada del
+ * modelo más caro cuando ya se sabe que no se entrega; esta función vuelve a comprobarlas
+ * porque la garantía no puede depender de que quien llama lo haya hecho en ese orden.
+ *
+ * **Sin veredicto no se entrega.** Es lo que hace que «el juez no se puede usar» sea un
+ * fallo del entorno con la tarea esperando feedback, y no una entrega en silencio.
+ */
+export declare function decisionDeEntrega(medida: MedidaDeEntrega, veredicto: VeredictoDeTarea | undefined): Entrega;
+/**
+ * El motivo de una tarea que agotó su tope de rondas de escritura: qué pasó, qué no se aplicó y cómo seguir. Medido en una
+ * tarea real (Maset), el motivo de antes —«quedaron 3 escritura(s) esperando aprobación»— no decía que el turno se había
+ * cortado ni qué hacer con una ventana casi lista.
+ */
+/** El crítico de una tarea que no hizo el trabajo (`decisionDeEntrega`). */
+/** El crítico de una pantalla de Stitch pedida que no existe: la persona tiene que elegir el diseño. */
+export declare const criticoDePantallaNoEncontrada: (titulo: string) => string;
+export declare const CRITICO_SIN_HACER = "no hizo el trabajo: no cambi\u00F3 ning\u00FAn fichero del proyecto y el juez no la da por cumplida";
+/**
+ * ¿Explica el agente este bloqueante en su respuesta final? Cuando TODO lo que el bloqueante cita entre «» aparece en
+ * ella (sin mirar mayúsculas): lo nombra, así que lo decidió o dice por qué no está. Sin nada citado, no. Puro.
+ */
+export declare function omisionExplicada(bloqueante: string, respuestaFinal: string): boolean;
+/** El tope agotado dicho para el `## CRITICAL` de una tarea que se CIERRA: sin «Continuar», que una cerrada no tiene. */
+export declare const criticoDeTopeAgotado: (tope: number, pendientes: number) => string;
+export declare const motivoDeTopeAgotado: (tope: number, pendientes: number) => string;
+/** Cuántas comprobaciones visuales llegan al juez: las ÚLTIMAS, que son las que describen cómo quedó. */
+export declare const TOPE_DE_COMPROBACIONES_AL_JUEZ = 8;
+/**
+ * Una comprobación visual en UNA línea para el juez: la herramienta, sobre qué captura, y lo primero que dijo, recortado.
+ * Sin saltos de línea: acaba en un prompt y en una lista que se lee de un vistazo.
+ */
+export declare function lineaDeComprobacion(quien: string, sobre: string | undefined, texto: string, tope?: number): string;
+/**
+ * **El CIERRE de una tarea que acaba**: lo crítico y las observaciones, para el comentario del ticket.
+ *
+ * Decisión suya: una tarea de fondo NO se queda esperando a que la persona decida al acabar —se cierra siempre—, y lo
+ * que haya quedado mal se DICE en el comentario. Lo crítico (`Entrega.criticos`: cortada, sin escribir, un bloqueante
+ * visual) va bajo `## CRITICAL`; lo demás de la entrega —un rojo del juez, errores del verificador, que no corriera—
+ * son OBSERVACIONES: «si la completó con problemas o detalles, eso no es crítico». Del motivo se quitan los fallos que
+ * ya son críticos, para no contarlos dos veces. Puro.
+ */
+export interface CierreDeTarea {
+    criticos: string[];
+    observaciones: string[];
+}
+export declare function cierreDeLaEntrega(entrega: Entrega, veredicto: VeredictoDeTarea | undefined): CierreDeTarea;

package/dist/core/entrelazar.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Eventos que nacen FUERA del flujo del grafo, entrelazados con él.
+ *
+ * Existe por un silencio medido: un agente EXTERNO (Claude Code) corre en otro proceso, así
+ * que ni una de sus tools cruza el stream de langgraph — entre la línea de delegación y su
+ * respuesta final hay minutos sin nada que mirar, y una pantalla quieta se lee como que se
+ * ha colgado. Lo que hace falta no es una piel nueva: es que su actividad entre por el
+ * MISMO sitio que la de todos, para que el colapsador la agrupe igual (`core/notify.ts`),
+ * la bitácora la cuente igual y las tres pieles no se enteren de que hay dos orígenes.
+ *
+ * Es la misma forma que `conVerificacion`: un generador que envuelve a `aEventos`. La
+ * diferencia es que aquél añade AL FINAL y este tiene que intercalar MIENTRAS, que es lo
+ * único delicado de este fichero.
+ */
+import type { DomainEvent } from "./events.js";
+/**
+ * El buzón por el que se empujan esos eventos. Quien lo llena no sabe nada del flujo, y
+ * quien lo vacía no sabe nada de quién lo llena — que es lo que permite que el adaptador
+ * del agente externo viva en `agent/` sin conocer el turno.
+ */
+export declare class ColaDeEventos {
+    private cola;
+    private avisar;
+    /** Encola y despierta a quien esté esperando. Nunca bloquea a quien lo llama. */
+    empujar(evento: DomainEvent): void;
+    /** Se lleva lo que haya, de una vez. Vacío es una respuesta válida. */
+    vaciar(): DomainEvent[];
+    /**
+     * Una promesa que se resuelve cuando hay algo. Se guarda UN solo resolutor: si hubiera una
+     * cola de esperas, la de una vuelta anterior seguiría viva y despertaría de más.
+     */
+    esperar(): Promise<void>;
+}
+/**
+ * El flujo del grafo más lo que se vaya encolando, en el orden en que ocurre.
+ *
+ * **La trampa de este fichero, y la razón de que `siguiente` sea una variable:** un
+ * `AsyncIterator` no admite dos `next()` vivos a la vez —el segundo se comería un valor o
+ * reventaría según la implementación—, así que se pide UNA vez, se guarda la promesa y se
+ * vuelve a esperar la MISMA en cada vuelta de la carrera. Solo cuando esa promesa se ha
+ * consumido de verdad se pide la siguiente. Volver a llamar a `it.next()` en cada vuelta
+ * sería el bug clásico de este patrón: se pierden eventos justo cuando hay actividad en los
+ * dos lados, que es cuando esto se usa.
+ *
+ * Y lo que quede encolado cuando el flujo se agota se dice IGUAL, antes de terminar: un
+ * evento que llegó tarde no es un evento que no ocurrió.
+ */
+export declare function entrelazar(fuente: AsyncIterable<DomainEvent>, cola: ColaDeEventos): AsyncIterable<DomainEvent>;

package/dist/core/esfuerzo.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Cuánto tiene que PENSAR un modelo antes de contestar, y qué modelos admiten que se les
+ * pida.
+ *
+ * Es la tercera tabla de esta familia, detrás de `contextos.ts#TOPES` y de
+ * `modelos.ts#pideThinkingAdaptativo`, y existe por el mismo motivo que ellas: el
+ * parámetro no significa lo mismo en todos, lo que no se reconoce hay que OMITIRLO, y
+ * pedirlo a ciegas no da una respuesta peor — da un 400.
+ *
+ * **La unidad es el MODELO, nunca el proveedor**, y eso está medido: dentro de NVIDIA,
+ * `nvidia/nemotron-3-super-120b-a12b` acepta siete niveles y `openai/gpt-oss-20b` acepta
+ * tres, contra el mismo host y con la misma clave. Una tabla por proveedor habría sido
+ * falsa el primer día.
+ *
+ * **Y los niveles son una LISTA por modelo, no tres fijos.** Anthropic tiene cinco desde
+ * Opus 4.7 y cuatro en la 4.6; Gemini tres; `nvidia/nemotron-3` cinco y `openai/gpt-oss`
+ * tres. Pintar siempre los mismos tres daría, según el modelo, o un control recortado o
+ * dos opciones que hacen lo mismo sin decirlo — la misma clase de mentira que un contador
+ * a cero que nadie ha medido.
+ *
+ * **Lo desconocido devuelve `undefined`**: ni se ofrece control ni se manda parámetro. Es
+ * el mismo lado conservador de `pideThinkingAdaptativo`, y aquí es literal — un nivel
+ * mandado a quien no lo admite se contesta con un error duro, comprobado en los tres
+ * proveedores que se pudieron medir.
+ */
+import type { Agente } from "./agentes.js";
+import type { Proveedor } from "./modelos.js";
+/**
+ * Los niveles que este harness sabe nombrar.
+ *
+ * `none` NO está, y es deliberado: en DeepSeek significa «no pienses», o sea que es un
+ * INTERRUPTOR y no un nivel. Mezclar «cuánto» con «si» en el mismo desplegable haría que
+ * un control que se lee como una intensidad apagara una capacidad.
+ */
+export type Esfuerzo = "low" | "medium" | "high" | "xhigh" | "max";
+export declare const ESFUERZOS: readonly Esfuerzo[];
+export declare function esEsfuerzo(valor: string): valor is Esfuerzo;
+/**
+ * Lo que el servidor ha dicho de ESTE modelo, cuando se le puede preguntar.
+ *
+ * Hoy solo Ollama, y por eso el campo es uno solo: su `POST /api/show` devuelve
+ * `capabilities`, y ahí está `"thinking"` o no está. Medido: `granite4.2:3b`,
+ * `glm-5.3-flash:cloud` y `qwen3.8:27b-mlx` la tienen; `ministral-3:3b` no, y pedirle que
+ * piense contesta `"ministral-3:3b" does not support thinking`.
+ *
+ * Entra por PARÁMETRO en vez de consultarse aquí porque son dos cadencias distintas y este
+ * módulo es puro: preguntar es asíncrono, toca la red y vive en `agent/`. Es el mismo
+ * reparto que ya declara `contextos.ts` sobre el `max_input_tokens` del catálogo vivo, solo
+ * que aquí el dato sí llega — quien lo rellena es `agent/config/catalogoModelos.ts`.
+ */
+export interface CapacidadesVivas {
+    /** ¿El servidor dice que este modelo piensa? Ausente = no se ha preguntado. */
+    piensa?: boolean;
+}
+/**
+ * Los niveles de esfuerzo que admite un modelo, o `undefined` si no admite ninguno —que es
+ * también lo que se devuelve cuando no se sabe, porque no saberlo y no poder son lo mismo
+ * para quien tiene que decidir si manda el parámetro.
+ *
+ * **Ollama va por las capacidades vivas y no por la tabla**, y esa asimetría es el hallazgo
+ * que la justifica: sus modelos los elige el usuario y no hay prefijo que los describa, pero
+ * el servidor contesta por cada uno. Sin capacidades —porque aún no se preguntó— no se
+ * afirma nada, que es distinto de afirmar que no puede.
+ */
+export declare function nivelesDeEsfuerzo(proveedor: Proveedor, modelo: string, vivas?: CapacidadesVivas): readonly Esfuerzo[] | undefined;
+/**
+ * Lo que el servidor de Ollama valida, y está medido en su propio mensaje de error: un
+ * `think: "banana"` contesta `must be "high", "medium", "low", "max", true, or false`.
+ *
+ * O sea que Ollama SÍ tiene niveles; que el tipo de `@langchain/ollama` los declare como un
+ * `boolean` es una limitación del cliente y no del servidor, y el cliente pasa el valor tal
+ * cual al request.
+ *
+ * **Y aquí hay un límite declarado que no se puede cerrar desde esta tabla**: que el
+ * servidor acepte el nivel no significa que el modelo lo honre. Medido: en `granite4.2:3b`
+ * solo `low` cambia algo y `medium`/`high`/`max` son idénticos entre sí; en
+ * `glm-5.3-flash:cloud` —que es el modelo POR OMISIÓN de este repo— `high` se comporta como
+ * apagado y solo `medium` piensa. No es monótono y no lo podemos arreglar: lo pone el
+ * template de cada modelo. Quien pinte esto tiene que DECIRLO.
+ */
+export declare const NIVELES_DE_OLLAMA: readonly Esfuerzo[];
+/**
+ * El nivel que se va a usar de verdad, dado lo que el usuario eligió y lo que el modelo
+ * admite.
+ *
+ * Existe porque elegir y aplicar están separados en el tiempo: el esfuerzo se fija una vez
+ * y el modelo se cambia después, así que un `xhigh` elegido con Opus 5 sigue puesto cuando
+ * alguien se pasa a Gemini, que no lo tiene. Ahí NO se manda el parámetro y NO se sustituye
+ * por el más parecido: bajar `xhigh` a `high` por nuestra cuenta sería decidir en nombre de
+ * alguien, y en este harness eso se paga en tokens que no pidió.
+ */
+export declare function esfuerzoAplicable(elegido: Esfuerzo | undefined, proveedor: Proveedor, modelo: string, vivas?: CapacidadesVivas): Esfuerzo | undefined;
+/**
+ * A qué CLASE de trabajo pertenece un subagente, sacada de sus DATOS y no de su nombre (mismo
+ * criterio que `recibeBuscarIcono`): un subagente propio con `ejecucion: true` es de la misma
+ * clase que `device-controller`.
+ *
+ * Solo hay una clase con nivel por omisión: **`mecanica`**, quien EJECUTA comandos y lee salidas.
+ * Consultor y analista son los dos `soloLectura` y no hay dato que los separe, y uno es una
+ * búsqueda y el otro escribe el plan; escritores y orquestador son donde se cometen los errores.
+ * Ahí no se decide por nadie: se queda lo que haga el proveedor.
+ */
+export type ClaseDeTrabajo = "mecanica";
+export declare function claseDeTrabajo(a: Pick<Agente, "ejecucion">): ClaseDeTrabajo | undefined;
+/**
+ * El interruptor de PENSAMIENTO, aparte del esfuerzo: «cuánto» y «si» son preguntas distintas (`none` no está
+ * entre los niveles por eso mismo). Un `.md` lo declara (`pensamiento: apagado`); ausente decide la familia.
+ */
+export type Pensamiento = "apagado" | "activo";
+export declare function esPensamiento(valor: string): valor is Pensamiento;
+/**
+ * Qué modelos admiten apagar el pensamiento con `thinking: {type: "disabled"}`. Solo DeepSeek, y MEDIDO contra la
+ * API: sin nada piensa, con `low` o `high` piensa casi igual (25, 23 y 23 tokens con una pregunta fácil), y con
+ * `thinking` desactivado la salida bajó de 27 tokens a 1. Lo demás no se sabe, y un parámetro que un modelo no
+ * conoce se paga en un 400: sin fila no hay interruptor.
+ */
+export declare function admiteApagarElPensamiento(proveedor: Proveedor, modelo: string): boolean;
+export declare function pensamientoPorOmision(proveedor: Proveedor, clase: ClaseDeTrabajo | undefined): Pensamiento | undefined;
+/** El pensamiento que se va a aplicar de verdad: lo que dice el agente, o la omisión de su familia, y solo si el modelo lo admite. */
+export declare function pensamientoAplicable(elegido: Pensamiento | undefined, proveedor: Proveedor, modelo: string, clase: ClaseDeTrabajo | undefined): Pensamiento | undefined;

package/dist/core/esqueleto.d.ts

@@ -0,0 +1,38 @@
+/**
+ * El esqueleto de un proyecto XOne mínimo, como DATOS y sin tocar el disco.
+ *
+ * Todo el contenido sale del «Hola Mundo» de la documentación XOne
+ * (`xone-help-docs`, topico 01 §9 y guia de UI §8.2): **nada inventado**. XOne
+ * ignora en silencio lo desconocido, así que un atributo o una función
+ * inventada no da error — da un bug mudo, y un esqueleto recién creado que no
+ * arranca sería la peor primera impresión posible.
+ *
+ * La escritura en disco vive en `agent/config/crearProyecto.ts`: aquí solo se DECIDE
+ * qué ficheros hay y qué llevan dentro, que es exactamente lo que se puede
+ * probar sin conexión, sin simulador y sin clave (el invariante de `npm test`).
+ */
+export interface DatosDelProyecto {
+    /** Nombre interno, sin espacios ni caracteres especiales (`Name=` del app.ini). */
+    nombre: string;
+    /** Título visible de la aplicación. */
+    titulo: string;
+    orientacion: "portrait" | "landscape";
+    /** Con login: `autologon="false"`, `<login-coll>` en app.xml y `Login.xne`. */
+    login: boolean;
+}
+export interface Ficha {
+    /** Ruta relativa a la raíz del proyecto. */
+    ruta: string;
+    contenido: string;
+}
+/**
+ * Las carpetas del runtime, VACÍAS y a propósito:
+ *
+ * - `bd/`: el `gestion.db` lo GENERA el simulador; un `.db` escrito a mano no
+ *   sería una base de datos, sería un fichero que estorba.
+ * - `icons/`: los PNG no se pueden generar aquí (salen de Material Icons
+ *   convertidos con cairosvg). La carpeta existe porque `app.ini` la declara.
+ * - `files/`: la carpeta de archivos dinámicos del runtime.
+ */
+export declare function carpetasDelEsqueleto(): string[];
+export declare function generarEsqueleto(datos: DatosDelProyecto): Ficha[];

package/dist/core/estiloMedido.d.ts

@@ -0,0 +1,70 @@
+/**
+ * El ESTILO de cada control, MEDIDO en los píxeles de su caja: lo que `descripcionDePantalla.ts` le pedía al modelo
+ * (forma, fondo, color del texto, tamaño de la letra, borde, texto recortado, alineación), sacado de la imagen con
+ * aritmética. Puro: recibe los píxeles ya en RGBA.
+ *
+ * Existe porque describirlo con el modelo no sirvió, medido sobre la calculadora de MyAllXOne: la MISMA imagen
+ * descrita dos veces salía con diecisiete teclas de otra forma y colores a más de cien puntos, y ninguna de dos
+ * pasadas vio el «12 + 3» recortado del visor. Con las cajas del árbol de controles (la captura) o del `code.html`
+ * renderizado (la maqueta), cada medida es la misma cada vez y cuesta milisegundos.
+ *
+ * Cómo se mide, dentro de la caja de un control:
+ * - **Fuera**: el color del anillo de píxeles que rodea la caja (lo que hay detrás).
+ * - **Fondo**: el color más repetido dentro de la caja, si se distingue de lo de fuera; si no, el control no pinta
+ *   fondo propio (un texto suelto) y no tiene forma que medir.
+ * - **Forma**: sobre el rectángulo que ocupa el fondo, cuánto se come cada esquina (radio) frente al lado corto, y
+ *   la proporción ancho/alto: recta, redondeada, píldora o círculo.
+ * - **Tinta**: los píxeles lejos del fondo Y de lo de fuera: el texto o el icono. De ahí el color del texto, la
+ *   altura de la letra (en fracción del ANCHO de la pantalla: aparato y maqueta tienen distinta proporción de alto) y
+ *   la alineación.
+ * - **Recortado**: hay tinta en la primera o la última fila de la caja: las letras siguen más allá del borde.
+ * - **Borde**: los lados de la caja (o del fondo) son una línea de un color distinto del de dentro.
+ */
+import type { ImagenRgba } from "./compararCapturas.js";
+import type { Caja } from "./geometriaDePantalla.js";
+import type { ControlVisto, Forma, Letra, PantallaDescrita } from "./descripcionDePantalla.js";
+/** Un control medido: los campos de estilo de `ControlVisto`, con las cifras de las que salen sus categorías. */
+export type EstiloMedido = Omit<ControlVisto, "texto" | "unidades" | "centro">;
+/** Las categorías de forma a partir de las cifras. Pura y exportada para el test. */
+export declare function formaDe(radio: number, proporcion: number): Forma;
+/** El tamaño de letra a partir de su altura (fracción del ancho de pantalla). */
+export declare function letraDe(altura: number): Letra;
+/** Mide un control. `img` es la imagen entera; `caja`, en sus píxeles. Lo que no se puede medir no se pone. */
+export declare function medirControl(img: ImagenRgba, caja: Caja): EstiloMedido;
+/** Un control que medir: su texto (o `[NOMBRE]` si no tiene) y su caja en los píxeles de la imagen. */
+export interface ControlAMedir {
+    texto: string;
+    caja: Caja;
+    /**
+     * Su caja ABRAZA su texto (un `<span>` de la maqueta, no un botón): dónde cae el texto dentro de ella no dice nada,
+     * así que su alineación no se mide. Medido en Maset: cada título salía «centrado» y el del aparato «a la izquierda».
+     */
+    ajustado?: true;
+    /**
+     * La caja de su ENVOLTORIO (`geometriaDePantalla.ts#cajaParaElEstilo`: el frame que hace de botón o de píldora). De
+     * ella salen la forma, el fondo y el borde; de la propia, lo de la LETRA —recorte, tamaño, color, alineación—, que es
+     * de la etiqueta: medido sobre el frame, el «RAD» recortado de la calculadora dejaba de verse.
+     */
+    envoltorio?: Caja;
+}
+export declare function pantallaMedida(img: ImagenRgba, filas: readonly (readonly ControlAMedir[])[]): PantallaDescrita;
+/** Los bloques que no están dentro de otro: la cabecera y no su título, el visor y no sus filas. Pura. */
+export declare function bloquesDeFuera(cajas: readonly Caja[]): Caja[];
+/** Un bloque y la imagen en la que vive, con la franja útil de la pantalla (sin barras del sistema), en píxeles. */
+export interface BloquesAMedir {
+    img: ImagenRgba;
+    bloques: readonly Caja[];
+    util: {
+        arriba: number;
+        abajo: number;
+    };
+}
+/**
+ * Compara el COLOR y la FORMA de los bloques anchos, emparejados por su altura relativa dentro de la franja útil de
+ * cada pantalla (la maqueta y el aparato no tienen la misma proporción). Pura. Existe por la calculadora: una cabecera
+ * amarilla donde la maqueta tiene la del fondo oscuro no la veía nadie, porque solo se comparaban los botones.
+ *
+ * Solo dice DIFERENCIAS de lo emparejado: un bloque sin pareja no es noticia, porque los dos lados no parten igual
+ * (el aparato puede tener un bloque por fila de teclas donde la maqueta tiene un solo panel).
+ */
+export declare function compararBloques(maqueta: BloquesAMedir, aparato: BloquesAMedir): string[];