xonecode 0.38.44 → 0.39.2

package/dist/web/servidor/consolaDeTarea.d.ts

@@ -0,0 +1,166 @@
+/**
+ * La `Consola` con la que corre una tarea en background.
+ *
+ * **Aplica lo que escribe, y aparca lo que necesita a una persona.** Son dos cosas
+ * distintas y esa distinción es todo el fichero.
+ *
+ * **Por qué APLICA** (§0 del diseño, decisión del usuario): la aprobación no estaba por la
+ * propiedad del repo, estaba porque XOne ignora en silencio lo desconocido —un atributo
+ * inventado no da error sino un bug mudo— y el diff era el único momento en que alguien lo
+ * veía antes de que existiera. La autorización de una tarea es el acto de CREARLA: elegir
+ * un proyecto y escribir un encargo es decir «trabaja en esto sin preguntarme», y por eso
+ * no hay ningún interruptor nuevo que armar — sin tarea creada no hay escritura autónoma
+ * posible. El sitio que deja libre el modal lo ocupan el verificador del turno
+ * (`turnoReal.ts#conVerificacion`, que corre por este camino igual que por el de una
+ * persona — MEDIDO) y el juez de la entrega.
+ *
+ * **Y NO es el MODO DE ESCRITURA de una sesión** (`core/modoDeEscritura.ts`). Ese dice «el
+ * humano que está aquí ha decidido
+ * no pulsar» —lo calcula como `interactivo && !eof()`— y aquí no hay nadie aquí: con esta
+ * consola devuelve `false` siempre, así que reutilizarlo habría dejado a las tareas sin
+ * aplicar nada. Y al revés: la marca del `settings.json` de un proyecto offline no decide
+ * sobre las tareas de nadie. Dos autorizaciones distintas, con alcances distintos.
+ *
+ * **Lo autorizado se DICE**, por dos canales y con los NOMBRES: al transcript (que es lo que
+ * lee quien abre la sesión) y por `autorizado`, que el corredor guarda en la tarea. Una
+ * escritura que nadie aprueba no puede ser además muda — es la regla del evento `artefacto`
+ * y la del aviso de honestidad del modo autónomo, y aquí es el ÚNICO aviso que
+ * hay: el de `turnoReal.ts` sale solo por su rama `todoAutomatico`, que este camino no
+ * toma. Con los nombres y no un contador, porque un contador a secas es el aviso que enseña
+ * a ignorar los avisos.
+ *
+ * **Lo que se apunta es lo AUTORIZADO, no lo escrito, y de ahí sale el nombre.** La decisión
+ * se toma antes de que el backend escriba, así que una ruta que las guardas de ruta rechazan
+ * —`/artifacts/`, una vista aplanada, `/.env`— se apunta aquí y no aparece en el disco
+ * (medido en el test de este fichero: las cinco se siguen rechazando, unas por el backend y
+ * otras por `permisosDe`). En el transcript eso se ve como esta línea seguida de la línea de
+ * la tool marcada en ERROR, que es cómo quien lo lee recupera la verdad — y es la razón de
+ * que las guardas devuelvan `{error}` en vez de lanzar. Quien dice qué hay en el disco es
+ * git, y eso se lee en Revisión con la ref de la sesión. La misma imprecisión tiene
+ * `aplicadasSinPreguntar` en `turnoReal.ts`, y por el mismo motivo.
+ *
+ * **Lo que NO cambia: `preguntar` y `leerSecreto`.** Aplicar una escritura no es contestar
+ * por una persona. Hoy una consola de proyecto sin
+ * cliente enganchado rechaza toda aprobación en silencio —`consolaWeb.eof()` es
+ * `!transporte.conectado()`— y contesta cadena vacía a cada pregunta. Para una tarea
+ * autónoma eso es la peor combinación posible: el turno «acaba» y nadie se enteró de que
+ * nada se aplicó. Aquí lo que no puede resolverse sin una persona se APARCA con su motivo,
+ * que es lo único que hace que el estado «requiere atención» sea verdad.
+ *
+ * **`aparcar` FUE el único canal, y ya no lo es — son dos, y hacen dos cosas distintas.**
+ * Cuando esto se escribió, `EjecutorDeTurno` devolvía `Promise<void>` y `crearEjecutorReal`
+ * (`cli/main.ts`) tiraba el retorno de `sesion.turno`, así que el `cortadoPorTope` que sabe
+ * que quedaron escrituras sin aplicar no salía de ahí y una tarea que se topaba con una
+ * aprobación acababa marcada «terminada». Hoy ese canal existe: el ejecutor devuelve
+ * `ResultadoDeTurno | void` (`cli/consola.ts`), `main.ts` lo devuelve y `vestibulo.ts` lo
+ * reenvía, y `pendientes` es una de las tres condiciones de la entrega
+ * (`core/entrega.ts`). Los dos siguen haciendo falta y no se pisan: **`aparcar` es lo que
+ * pasa cuando el turno no puede seguir** —alguien tenía que decidir y no había nadie— y el
+ * RESULTADO es lo que el turno cuenta cuando sí acabó. Sin `aparcar`, un turno que se topa
+ * con una pregunta se remataría solo; sin el resultado, uno que acaba dejando escrituras
+ * colgando se daría por bueno.
+ *
+ * No se guarda el `interrupt` esperando una decisión: el proceso puede vivir días y morir
+ * en medio. La aprobación se retoma al abrir la sesión —`saldarAprobacionesHuerfanas` salda
+ * las llamadas colgadas diciendo la verdad, el modelo vuelve a proponer la escritura y ahí
+ * ya hay una persona delante—.
+ *
+ * **Una consola por TURNO.** El «se aparca una vez» de abajo vale por turno porque quien la
+ * monta (el corredor, en su `correrTarea`) construye una por turno. Reutilizarla para un
+ * segundo turno lo dejaría mudo.
+ */
+import type { Consola } from "../../cli/consola.js";
+import type { Escribir } from "../../cli/stdio.js";
+import type { Piel } from "../../core/turno.js";
+import type { CatalogoModelosPort, Papel } from "../../core/ports.js";
+/**
+ * El mensaje que acompaña al rechazo, hermano de `REJECT_MESSAGE` (`vendor/hitl.ts`).
+ *
+ * **Quién lo usa desde que las escrituras se aplican**: hoy, el corte de `preguntar` — y
+ * nada más. La otra rama, la pendiente que NO admite `approve`, es defensiva y **no se
+ * alcanza**: `decisionesPermitidas` viene del `reviewConfigs` del interrupt, y el único que
+ * los fija en este repo es `perfiles.ts`, que siempre pone `["approve", "reject"]`. Se deja
+ * puesta porque aprobar una pendiente que no admite `approve` sería inventarse una decisión
+ * que la librería no acepta, y la dirección de fallo ahí tiene que ser rechazar y aparcar
+ * —fail-closed— el día que alguien añada una tool que solo ofrezca rechazo. Dicho como
+ * defensiva y no como camino vivo a propósito: un comentario que da por ocurrido lo que no
+ * ocurre es la trampa que este repo ya ha pagado varias veces.
+ *
+ * Se copian sus tres cláusulas operativas —no se ejecutó, no lo reintentes, DILO en la
+ * respuesta final— porque su docblock describe exactamente el fallo que aquí más duele: un
+ * rechazo pelado deja al modelo rematar el turno como si la escritura hubiese quedado
+ * lista, y en una tarea de fondo el transcript es lo único que una persona leerá después.
+ *
+ * Lo que NO se copia es la atribución: el original dice «RECHAZADO por el usuario», y en
+ * una tarea de fondo ningún usuario rechazó nada. Ese detalle acabaría en la respuesta
+ * final contando un rechazo que nunca hubo, que es la misma clase de mentira que este
+ * fichero existe para evitar.
+ */
+export declare const MENSAJE_DE_RECHAZO_DE_TAREA: string;
+/**
+ * Se pidió algo que solo una persona puede contestar, y no había ninguna.
+ *
+ * **Cortar el turno es la única salida honesta de `preguntar`.** No tiene valor de
+ * «rechazo»: devuelve una cadena, y cualquier cadena que se devuelva el agente la toma por
+ * la respuesta de un humano. La cadena vacía tampoco sirve — `cli/aprobar.ts` la documenta
+ * contada a mano: de sus 18 llamadores, 16 la leen como «cancela / usa el valor por
+ * omisión», y «usa el valor por omisión» es una decisión que aquí nadie ha tomado. Es
+ * además el error que este repo ya declara: «esa cadena vacía sola NO rechaza; aquí decía
+ * que sí y era falso».
+ *
+ * Cortar desde dentro no es un camino nuevo: es lo que hace el «sin humano» de `cli/run.ts`
+ * lanzando desde `pedirAprobacion`, y `turnoReal.ts` tiene un `catch` puesto para él.
+ * Medido: una excepción desde ahí sale por `sesion.turno` y llega a quien corre el turno.
+ * Con `aparcar` llamado ANTES de lanzar, el motivo bueno ya está escrito cuando el corredor
+ * recoja el error — y su `motivo ??=` conserva el primero.
+ *
+ * **La asimetría, dicha para que se encuentre en un `grep` y no en un turno que no cierra:**
+ * ese `catch` de `turnoReal.ts` envuelve SOLO la llamada a `pedirAprobacion`, no el cuerpo
+ * del bucle. Hoy da igual, y por eso no se ha ampliado: dentro de un turno de tarea las
+ * aprobaciones van por `aprobacionesTui`, así que la rama `pedirDecisiones` —la única que
+ * usa `Consola.preguntar` dentro del turno— no se toma nunca, y ampliar el `catch` sería
+ * código para una hipótesis. Pero si algún día un `preguntar` acaba DENTRO de un turno, la
+ * excepción de aquí se saltará ese `catch` y **ese turno se queda sin `piel.fin`**: sin
+ * línea de tiempo en stdio y sin plegarse en la web. Entonces hay que ampliarlo al cuerpo
+ * del bucle. La tarea sí queda aparcada y con su motivo en los dos casos, que es la
+ * propiedad que sostiene todo esto.
+ */
+export declare class ErrorDeTareaSinHumano extends Error {
+    constructor(motivo: string);
+}
+export declare function crearConsolaDeTarea(opciones: {
+    /** Aparca la tarea con este motivo. Se llama UNA vez por turno. */
+    aparcar: (motivo: string) => void;
+    /**
+     * Las escrituras que se acaban de AUTORIZAR sin que nadie las aprobara, con ruta relativa.
+     *
+     * «Autorizar» y no «aplicar»: esto se llama cuando se toma la decisión, y el backend
+     * puede rechazar la ruta después (ver la cabecera). El nombre del campo donde acaba
+     * (`Tarea.autorizadas`) dice lo mismo y por lo mismo.
+     *
+     * Se llama una vez por TANDA aprobada y no una por turno, al contrario que `aparcar`: un
+     * turno aplica en varias rondas de aprobación (medido: cuatro en un turno que insiste), y
+     * quedarse con la primera escondería los demás ficheros. Quien lo recoge —el corredor—
+     * los acumula y los guarda en la tarea.
+     *
+     * Opcional porque quien monta esta consola puede no tener dónde guardarlos; entonces lo
+     * autorizado se dice igualmente en el transcript, que es lo que no puede faltar.
+     */
+    autorizado?: (ficheros: readonly string[]) => void;
+    escribir: Escribir;
+    /**
+     * La piel con la que el turno se pinta. Ausente y `crearEjecutorReal` cae en
+     * `crearPielStdio(escribir)`, que es texto de consola metido en actos `sistema`: la sesión
+     * de la tarea se guarda, pero degradada — sin actos de asistente, ni de razonamiento, ni
+     * las tarjetas de artefacto, o sea una pared de líneas grises donde debería leerse una
+     * conversación. Quien la monte debería pasarle la piel de la consola de PROYECTO, que es
+     * la que sabe hacer actos de verdad; entra por aquí y no se construye dentro porque esta
+     * capa no conoce el transporte de esa consola.
+     */
+    piel?: () => Piel;
+    catalogoModelos: CatalogoModelosPort;
+    guardarModeloGlobal: (papel: Papel, id: string) => {
+        ruta: string;
+        id: string;
+    };
+}): Consola;

package/dist/web/servidor/consolaWeb.d.ts

@@ -0,0 +1,142 @@
+import { type MensajeAlCliente, type MensajeDelCliente, type Sumidero } from "./transporte.js";
+import type { Acto, ConsumoDeTurno } from "../../core/actos.js";
+import { type Consola } from "../../cli/consola.js";
+import { type CatalogoModelosPort } from "../../core/ports.js";
+export interface OpcionesDeConsolaWeb {
+    /** Inyectable para poder probar el vencimiento sin esperarlo de verdad. */
+    msDeEspera?: number;
+    /** El reloj con que se fechan los mensajes y las respuestas (IXCODE-24). Inyectable para los tests. */
+    ahora?: () => number;
+    catalogoModelos?: CatalogoModelosPort;
+    guardarModeloGlobal?: Consola["guardarModeloGlobal"];
+    /**
+     * Lo consumido ACUMULADO por la sesión, si consta. Entra por opción y no se lee de ningún
+     * cierre de aquí por el mismo motivo que los modelos: quien conoce la sesión es el
+     * vestíbulo, y este módulo no sabe de ninguna.
+     *
+     * La piel lo consulta al cerrar cada turno para estampar su DELTA en el acto `fin`, que es
+     * de donde una sesión reabierta saca sus totales. Ausente = no se persiste consumo y los
+     * `fin` salen sin él, que es «no consta».
+     */
+    consumoAcumulado?: () => ConsumoDeTurno | undefined;
+    /**
+     * Si hay un turno en marcha, intenta apuntar el texto AHÍ en vez de encolarlo como línea
+     * nueva (IXCODE-4). `true` si lo consumió así — `recibir` no encola nada más—; `false` o
+     * ausente y `recibir` sigue el camino de hoy. Quien inyecta esto (`vestibulo.ts`) es quien
+     * sabe si hay turno en vuelo y tiene la sesión real; este módulo no sabe de ninguna.
+     */
+    notaMientrasTrabaja?: (texto: string) => boolean;
+    /** El botón DETENER y replanificar (IXCODE-4), con el mismo contrato que `notaMientrasTrabaja`:
+     *  `true` si se aplicó al turno en marcha; `false` o ausente y la prosa sigue como siempre. */
+    detenerMientrasTrabaja?: (texto: string) => boolean;
+    /**
+     * IXCODE-7: compone el texto con el inventario de los adjuntos del mensaje —
+     * `conAdjuntos(texto, listarAdjuntosDeSesion(raiz, idDeHilo, nombres), "mensaje")`—. Lo
+     * construye el vestíbulo, que es quien sabe la raíz del proyecto y el id de la sesión; este
+     * módulo no toca disco. Ausente = la prosa con adjuntos viaja tal cual, como hoy (y entonces
+     * NINGÚN nombre se afirma: sin poder comprobar el disco no hay nada que prometer).
+     *
+     * **Devuelve `adjuntos`, los nombres que DE VERDAD encontró** (`listarAdjuntosDeSesion` ya
+     * filtra a los que existen, en el orden pedido) — no los `nombres` que se le pasaron. Ronda
+     * de arreglo 1/5: un nombre bien formado que nunca se subió pasaba la lista blanca de forma
+     * (`nombreDeAdjuntoAceptable`) y el acto de usuario afirmaba un adjunto que el agente nunca
+     * vio, porque `listarAdjuntosDeSesion` no lo encontraba. El acto ahora se anota SOLO con lo
+     * que esta función confirmó.
+     */
+    conAdjuntosDelMensaje?: (texto: string, nombres: readonly string[]) => {
+        texto: string;
+        adjuntos: string[];
+    };
+}
+export interface ConsolaWeb {
+    /**
+     * Mete una línea en la cola del lazo SIN acto de usuario. Es para lo que dispara un
+     * control de la interfaz, no una persona: `recibir({clase:"prosa"})` anota un acto de
+     * usuario —y debe: el transcript se le debe a quien escribió la petición—, pero un botón
+     * no escribió nada.
+     *
+     * No es un mensaje del cable: el cliente manda la INTENCIÓN (`clase: "modelo"`) y es el
+     * servidor quien decide que aplicarla es reusar el manejador de `COMANDOS`.
+     */
+    /** Dice si hay turno en vuelo. Lo llama el envoltorio del ejecutor (`vestibulo.ts`), que
+     *  es el único que sabe cuándo empieza y cuándo acaba. */
+    /** `detenible`: el turno en marcha admite DETENER y replanificar (el botón se pinta). */
+    turno(activo: boolean, detenible?: boolean): void;
+    /**
+     * Encola una línea COMO COMANDO, que es como el servidor aplica `/modelo`, `/aprobacion` o
+     * `/sync` sin que nadie teclee la sintaxis.
+     *
+     * `sustituye` es la CLAVE de un control que refleja un ESTADO: si ya hay otra pendiente con
+     * la misma clave, aquélla se retira. Opcional a propósito — ver `LineaDeConsola`.
+     */
+    encolar(linea: string, sustituye?: string): void;
+    consola: Consola;
+    /** Un mensaje del navegador, tal cual llega por `POST /accion`. */
+    recibir(mensaje: MensajeDelCliente): void;
+    /**
+     * La `respuesta` de un MÓVIL de la sesión remota. No es `recibir`: al móvil solo le llega una
+     * `pregunta` SIN `decision` (`core/remoto.ts#filtrarSalida`), así que su respuesta solo puede
+     * contestar una de ésas — nunca la subida con casillas ni «¿Vaciar la copia…?», que el
+     * escritorio tiene abiertas y el móvil no ha visto. `false` = no había ninguna que contestar
+     * y no se ha tocado nada.
+     */
+    responderDesdeElMovil(texto: string): boolean;
+    /** El cliente abre el SSE; devuelve los actos con los que hay que reemitirle el transcript. */
+    conectar(enviar?: Sumidero): readonly Acto[];
+    /**
+     * Alguien MIRA lo que esta consola pinta sin ser su cliente: la vista en vivo de una tarea
+     * de fondo. Devuelve el transcript de ese instante, como `conectar`.
+     *
+     * **No es `conectar`, y esa es toda la razón de que exista.** `eof()` es
+     * `!transporte.conectado()`, así que un `conectar` de más le diría a esta consola que hay
+     * un humano al que preguntar — y en la consola de una tarea eso es falso por
+     * construcción: la vista es de solo lectura, no tiene compositor, y nadie puede contestar
+     * una pregunta ni aprobar una escritura desde ahí. Medido antes de escribirlo: con
+     * `conectar`, el `eof()` de la consola de una tarea pasaba de `true` a `false`. Ver
+     * `Transporte.mirar` para lo que un mirón recibe (solo el transcript) y lo que no.
+     */
+    mirar(enviar: Sumidero): readonly Acto[];
+    /** Se va UN mirón, y los demás siguen. */
+    dejarDeMirar(enviar: Sumidero): void;
+    /** Se va UN cliente (el sumidero que se pasa) o todos (sin argumento). Ver `Transporte`. */
+    desconectar(enviar?: Sumidero): void;
+    /** El cable se muda a otra consola: suelta los sumideros sin dar por ido al humano. Ver
+     *  `Transporte.soltar`, que es donde está la diferencia y por qué importa. */
+    soltar(enviar?: Sumidero): void;
+    /** Agota `lineas` (EOF) para que el lazo de `correrConsola` RETORNE, y corta el cliente. */
+    cerrar(): void;
+    actos(): readonly Acto[];
+    /**
+     * Cuántos actos del principio de `actos()` ya NO pueden cambiar: los de antes del último acto de
+     * la PIEL, que es el único que se sustituye (el cierre de una racha de tools, un parcial). Es lo
+     * que se puede volcar a disco A MITAD de turno sin escribir dos versiones del mismo acto ni
+     * desordenar el `.jsonl`.
+     */
+    estables(): number;
+    /** Apunta un acto que no viene ni de la piel ni de un comando: lo que el SERVIDOR resolvió por un
+     *  botón (una propuesta de tareas encolada o descartada). Se emite y entra en el transcript. */
+    anotar(acto: Acto): void;
+    eventosEmitidos(): readonly MensajeAlCliente[];
+    /**
+     * Las aprobaciones EN VUELO, y solo esas. Es el único sitio con contenido de fichero y
+     * diff, y se suelta en cuanto hay decisión: pasado ese momento nada de lo que el humano
+     * miró sigue en memoria, ni se persiste, ni se reemite al reconectar.
+     */
+    mensajesDeAprobacion(): readonly MensajeAlCliente[];
+    /**
+     * ¿Hay una pregunta de TEXTO LIBRE esperando a alguien? Las que llevan una `decision` (la
+     * subida, «¿Vaciar la copia…?») no cuentan: son diálogos del escritorio, no una pregunta
+     * del hilo, y son las mismas que `responderDesdeElMovil` no contesta.
+     */
+    hayPreguntaDeTextoPendiente(): boolean;
+    /**
+     * Se avisa cuando NACE o TERMINA una aprobación en vuelo, y cuando nace o termina una
+     * pregunta de texto libre (las de `decision` no avisan, por lo mismo que no cuentan arriba).
+     * Termina de cualquier forma: contestada, vencida o porque se fue el último cliente. El aviso
+     * no dice qué cambió: quien escucha vuelve a preguntar (`mensajesDeAprobacion`,
+     * `hayPreguntaDeTextoPendiente`), que en el instante del aviso ya dicen lo nuevo. Devuelve
+     * con qué darse de baja.
+     */
+    alCambiarEspera(oyente: () => void): () => void;
+}
+export declare function crearConsolaWeb(opciones?: OpcionesDeConsolaWeb): ConsolaWeb;