xonecode 0.38.44 → 0.39.2

package/dist/agent/motores/trueforge/detencion.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DETENER y replanificar (IXCODE-4): la persona pulsa el botón mientras el agente trabaja, los
+ * especialistas que estaban en marcha cierran con un resumen de lo hecho y lo que les quedaba, y
+ * el orquestador recibe esos resúmenes con el mensaje de la persona y replanifica.
+ *
+ * **No es una `Nota`, y a propósito**: una nota se entrega a CADA hilo como encargo (`notas.ts`),
+ * y una orden de parar repartida así haría que el hijo parase y el raíz… volviera a encargar lo
+ * mismo. Aquí cada destinatario recibe SU texto: el hijo, «para y resume»; el raíz, «replanifica
+ * sin repetir lo hecho».
+ *
+ * **A quién se detiene**: a los hijos nacidos de una llamada del raíz que empezó ANTES de pulsar.
+ * No basta «los vivos al pulsar»: si se pulsa mientras el raíz está decidiendo delegar, el hijo
+ * que sale de esa decisión nace después, pero de un plan que la persona ya no quiere. Y los que
+ * el raíz delegue DESPUÉS de leer la orden corren normal —son el plan nuevo—.
+ *
+ * **Cómo para un hijo, sin tocar la librería**: la orden entra por `preLLMProcessors` antes de su
+ * siguiente llamada, y SU modelo (`modeloParaTrueforge`, construido por hilo en `crearHijo`) tira
+ * las tool calls de esa respuesta: una respuesta sin tool calls cierra el hilo con normalidad
+ * (`AGENT_DONE`) y su texto le llega al padre como resultado de `create_sub_agent`. Se FILTRA lo
+ * que devuelve el modelo, no se le quitan las tools: con el historial lleno de llamadas, algún
+ * proveedor rechaza una petición sin la definición de tools.
+ *
+ * **Y una llamada EN CURSO se corta** (`corte`): medido con el botón, el analista estaba dentro de
+ * una llamada de 60 s generando un informe entero cuando se pulsó, y sin corte esa llamada acababa
+ * escribiéndolo. Cada hijo lleva su `AbortController`, que aborta SOLO su stream; el modelo del
+ * hijo lo captura y pide el resumen en el acto (`modeloLangchain.ts#corte`). Lo que NO se corta:
+ * un comando de shell en curso, que termina primero —la orden llega en la llamada siguiente—.
+ */
+/** Lo que llega al padre si el hijo, tras filtrar, no dejó texto. */
+export declare const RESUMEN_DE_RELLENO = "[Detenido a petici\u00F3n de la persona antes de poder resumir lo hecho.]";
+export declare function textoDeDetencionParaHijo(texto: string): string;
+export declare function textoDeDetencionParaRaiz(texto: string): string;
+/** El estado de la detención de UN turno. Lo crea la sesión y lo vacía al cerrar el turno. */
+export interface Detencion {
+    /** Lo que la persona escribió al pulsar; puede ir vacío. */
+    texto: string;
+    /** Se detienen los hijos nacidos de una llamada del raíz con índice ≤ éste. */
+    hastaLlamadaDelRaiz: number;
+    /** Hilos hijo que ya recibieron la orden (y cuyo modelo, desde entonces, no llama tools). */
+    avisados: Set<string>;
+    raizAvisado: boolean;
+}
+/** Lleva la cuenta que decide a quién se detiene: cuántas llamadas lleva el raíz, y de cuál nació
+ *  cada hijo. Uno por sesión; `reiniciar` al empezar cada turno. */
+export declare function crearControlDeDetencion(hiloRaiz: string): {
+    reiniciar(): void;
+    /**
+     * Cuántos hijos trabajan a la vez AHORA: los nacidos de la última llamada del raíz. Mientras un
+     * hijo vive, el raíz espera su resultado y no vuelve a llamar al modelo, así que lo nacido de
+     * llamadas anteriores ya terminó. Lo usa el reparto de notas (`notas.ts`).
+     */
+    hijosVivos(): number;
+    /** Al crear un hijo: nace de la llamada del raíz en curso. */
+    nacio(threadId: string): void;
+    detener(texto: string): void;
+    /** Para el modelo de un hijo, al empezar cada llamada: su señal de corte y la orden que se le da
+     *  si se corta. Darla lo cuenta como avisado —no la recibe otra vez por el procesador—. */
+    corte(threadId: string): {
+        senal: AbortSignal;
+        orden: () => string;
+    } | undefined;
+    /** Para el modelo de un hijo: si ya recibió la orden, su respuesta no puede llamar tools. */
+    soloTexto(threadId: string): boolean;
+    /** Lo que se le mete a ESE hilo antes de su llamada, si algo. Cuenta las llamadas del raíz. */
+    antesDeLlamar(threadId: string): string | undefined;
+    /** La orden que NADIE llegó a leer —ni el raíz— sale como el turno siguiente, igual que una
+     *  nota sobrante. Con texto vacío no queda nada que mandar. */
+    sobrante(): string | undefined;
+};
+export type ControlDeDetencion = ReturnType<typeof crearControlDeDetencion>;

package/dist/agent/motores/trueforge/esperas.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quién no arranca hasta que otro termine, entre HIJOS que el orquestador lanzó a la vez.
+ *
+ * El orquestador delega en paralelo cuando le parece independiente, y no siempre lo es: en una pasada real lanzó a
+ * `developer-xone` y a `designer-xone` a la vez, el desarrollador escribió el `.xne` antes de que el diseñador
+ * terminara y **9 de los 26 recursos del diseñador se quedaron sin usar**. La cola por FICHERO solo evita que dos
+ * escriban el mismo; no sabe de dependencias.
+ *
+ * ## Por qué NO se espera bloqueando (y la primera versión lo hacía)
+ *
+ * Es un dato del `.md` (`espera: [designer-xone]`). La primera versión paraba al desarrollador ANTES de cada
+ * llamada al modelo mientras el diseñador estuviera vivo, y **atascó la pasada**: la librería ejecuta todos los hilos
+ * activos juntos y solo devuelve el control cuando TODOS terminan su paso, y una aprobación de escritura del
+ * diseñador solo se atiende al devolver el control. El desarrollador, parado dentro de su espera, impedía que
+ * volviera, y el diseñador no podía acabar sin aprobación: un bloqueo mutuo, con la CPU a cero y sin ningún error. Los
+ * tests con dobles no lo vieron porque el diseñador doble no pedía aprobación.
+ *
+ * Así que ahora **no bloquea nunca**: si al crear el hijo hay uno vivo —o anunciado por el mismo mensaje del
+ * orquestador— de los que declara, el hijo **no arranca** y su llamada se devuelve al instante diciéndolo. El
+ * orquestador, que ya tiene el informe del otro cuando lo recibe, vuelve a llamarlo con él en el encargo.
+ */
+export interface Esperas {
+    /** El orquestador acaba de pedir un hilo de `nombre`; todavía no ha nacido. */
+    anunciar(nombre: string): void;
+    /** Nació un hilo de `nombre` (deja de estar solo anunciado). */
+    nacio(nombre: string, hilo: string): void;
+    /** El hilo terminó (bien o mal): deja de estar vivo y consta que `nombre` terminó. */
+    murio(hilo: string): void;
+    /** De esos nombres, cuáles hay vivos o anunciados ahora, sin contar `propio`. */
+    vivos(nombres: readonly string[], propio?: string): string[];
+    /** De esos nombres, cuáles han terminado en esta conversación. */
+    terminados(nombres: readonly string[]): string[];
+    /** Los hilos vivos y los anunciados se dieron por muertos (turno cortado, orquestador rehecho). Lo terminado consta. */
+    darPorMuertos(): void;
+    /** Otra conversación: se olvida todo. */
+    olvidar(): void;
+}
+export declare function crearEsperas(): Esperas;

package/dist/agent/motores/trueforge/eventosTrueforge.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Los eventos de TrueForge, en los eventos de dominio de XOneCode (`core/events.ts`).
+ *
+ * Es lo que hace la interfaz transparente al motor: las pieles —web, terminal, tareas— pintan
+ * eventos de dominio y no saben qué los produjo. Aquí se decide qué se cuenta de un turno de
+ * TrueForge, con las MISMAS reglas que `puente.ts` aplica a los chunks de deepagents:
+ *
+ * - **Ningún evento lleva argumentos de tool**: la línea de una tool lleva solo el `detalle` de la
+ *   lista blanca (`resumenDeTool.ts#detalleDe`), y el resultado de una tool no se pinta —
+ *   `write_file` llevaría el fichero entero—.
+ * - **Solo el hilo RAÍZ habla**: lo que dice un subagente no es la respuesta, igual que el
+ *   `esDelPadre` del puente. Sus tools sí se ven, que es lo que dice que está trabajando, y
+ *   su RAZONAMIENTO también, pero entero y no a trozos (`PensamientoPorHilo`).
+ *
+ * Puro sobre los eventos: guarda lo justo entre uno y otro (el uso de la última llamada) y no
+ * toca nada más.
+ */
+import type { DomainEvent } from "../../../core/events.js";
+/** El uso de UNA llamada al modelo, tal como lo adjunta TrueForge al mensaje completo. */
+export interface UsoDeLlamada {
+    input: number;
+    output: number;
+    cache: number;
+    /** Cuántos de los `output` fueron razonamiento. Ausente = el proveedor no lo dice (no es cero). */
+    razonamiento?: number;
+}
+/**
+ * El tope que agotó un hilo, si ESTE evento es ese corte; `undefined` si no. Vale para el raíz y
+ * para cualquier hijo, y existe para la traza: sin él, un especialista cortado por el tope era
+ * indistinguible de uno que terminó —medido: la traza decía «cortes: 0» con un documentador que
+ * se quedó en exactamente 30 llamadas a mitad de un manual—.
+ */
+export declare function topeAgotadoDe(evento: unknown): number | undefined;
+/**
+ * El especialista de un hilo hijo, si se sabe: lo contesta la sesión (`quienEs`), que es quien
+ * sabe qué hilo abrió cada delegación.
+ */
+export type EspecialistaDeHilo = (hilo: string) => string | undefined;
+/**
+ * El razonamiento de los HIJOS mientras llega, por hilo. El del raíz se pinta a trozos, en vivo;
+ * el de un especialista se guarda aquí y sale ENTERO cuando su mensaje se completa
+ * (`internal.agent.context.append`), delante de las tools que decidió. A trozos no se puede:
+ * dos especialistas en paralelo intercalan sus trozos, y la piel —que junta los trozos seguidos
+ * en un acto— los mezclaría en un párrafo que no pensó nadie.
+ *
+ * Uno por TURNO: lo que se quede a medias en un turno cortado no es del siguiente.
+ */
+export type PensamientoPorHilo = Map<string, string>;
+/**
+ * Un evento de TrueForge → cero o más eventos de dominio, y el uso si trae una llamada al modelo
+ * terminada (para que quien corre el turno lo sume al contador).
+ */
+export declare function traducirEvento(evento: unknown, especialistaDe?: EspecialistaDeHilo, pensamientos?: PensamientoPorHilo): {
+    eventos: DomainEvent[];
+    uso?: UsoDeLlamada;
+};

package/dist/agent/motores/trueforge/informesDeHijos.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Lo que ESCRIBIÓ un hijo, contado por el harness y entregado a quien lo llamó.
+ *
+ * Existe por una pasada real (calc10): el orquestador releyó `MenuPrincipal.xne` seis veces y la maqueta cinco tras
+ * las vueltas de sus especialistas, porque lo único que le volvía era el texto del hijo y no se fiaba de él. Ninguno
+ * de los harnesses revisados (opencode, qwen-code, aider, deepseek-harness, TrueForge) le pasa al padre qué cambió el
+ * hijo; aquí el harness ya lo sabe —cada `write_file`/`edit_file` que salió bien pasa por la sesión—, así que se le
+ * DICE: qué ficheros, cuántas ediciones y cuántas líneas entran y salen. Nunca el contenido.
+ *
+ * Llega como UN mensaje de usuario antes de la siguiente llamada del padre (`capacidadDeInformesDeHijos`), el mismo
+ * camino que los avisos de vueltas: la respuesta del hijo ya la entregó la librería y no se reescribe.
+ */
+import type { Capacidad } from "./capacidades.js";
+/**
+ * Las tools PROPIAS que escriben un BINARIO en el proyecto, con el principio de su texto de éxito. Sin contarlas, el
+ * informe decía «SIN escribir ningún fichero» de un diseñador que había traído siete fuentes, y el orquestador fue a
+ * comprobarlo al disco y mandó al de pruebas a mirar si estaban sanas (pasada real con la maqueta de la calculadora).
+ */
+export declare const ESCRITURAS_BINARIAS: Readonly<Record<string, string>>;
+export interface CambioDeFichero {
+    ediciones: number;
+    /** Lo creó `write_file` en este encargo. */
+    nuevo: boolean;
+    mas: number;
+    menos: number;
+    /** Lo escribió una tool de BINARIOS (`ESCRITURAS_BINARIAS`): no hay líneas que contar. */
+    binario?: boolean;
+}
+/** ¿Es `nombre` una tool de binarios? Por clave PROPIA: `in` daría por buena `constructor`. */
+export declare function esEscrituraBinaria(nombre: string): boolean;
+/** Lo que suma UNA escritura que salió bien, por sus argumentos (los de la tool, que nunca salen de aquí). */
+export declare function anotarEscritura(cambios: Map<string, CambioDeFichero>, nombre: string, args: Record<string, unknown>): void;
+/**
+ * ¿Salió bien? El texto de éxito es el de `toolsDeFichero.ts#ejecutar`, o el de la tool de binarios
+ * (`ESCRITURAS_BINARIAS`); un rechazo o un error no cuenta.
+ */
+export declare function escrituraConExito(contenido: unknown, nombre?: string): boolean;
+/**
+ * El informe para el padre. `escribe` dice si el hijo podía escribir el proyecto: a uno que no podía no se le
+ * atribuye nada, y a uno que podía y no escribió se le dice —un «ya está hecho» sin ninguna escritura es justo lo
+ * que el padre tiene que saber—.
+ */
+export declare function textoDelInforme(quien: string, cambios: ReadonlyMap<string, CambioDeFichero>, escribe: boolean, medida?: string): string | undefined;
+/**
+ * Entrega, antes de la siguiente llamada del hilo, los informes que le esperan (`pendientes` los CONSUME: cada uno
+ * sale una vez). Va en el raíz y en quien puede llamar a otros. No añade tools.
+ */
+export declare function capacidadDeInformesDeHijos(pendientes: (hilo: string) => string[]): Capacidad;

package/dist/agent/motores/trueforge/medidaAutomatica.d.ts

@@ -0,0 +1,37 @@
+import { type Comparacion } from "../../../core/compararCapturas.js";
+/**
+ * Rondas VISUALES por encargo: una por captura medida. calc9, calc12 y calc13 sacaron 20-25 capturas cada una, retocando
+ * una o dos cosas por despliegue. Con el aviso, la última se DICE: después se devuelve con lo que falta. Eran tres, y medido
+ * en Maset con DeepSeek flash el desarrollador devolvía a la tercera con una fila de la maqueta sin pintar: se subieron
+ * a cinco. El prompt del desarrollador dice este MISMO número (`textoDelBucle`).
+ */
+export declare const RONDAS_VISUALES = 5;
+/** El criterio de aceptación por omisión del bucle (`textoDelBucle`): por debajo, en vertical Y en horizontal. */
+export declare const CRITERIO_DE_DISTANCIA = 0.1;
+/**
+ * La maqueta de la sesión. PRIMERO la traída de Stitch (`/artefactos/diseno/screen.*`, `traerDeStitch.ts`):
+ * traerla es un acto de ESTA sesión, así que manda sobre una carpeta del proyecto que puede ser de otro
+ * encargo. Después `/diseno/screen.png`, la primera imagen de `/diseno/` y la de los adjuntos.
+ */
+export declare function buscarMaqueta(raiz: string, adjuntos?: string, artefactos?: string): {
+    virtual: string;
+    disco: string;
+} | undefined;
+/** La captura MÁS RECIENTE de la carpeta de artefactos escrita desde `desdeMs`, con su nombre relativo (dos niveles). */
+export declare function ultimaCaptura(carpeta: string, desdeMs: number): string | undefined;
+/** Mide una captura contra la maqueta. Lanza si alguna no se puede abrir o decodificar: quien llama lo traga. */
+export declare function medirContraMaqueta(captura: string, maqueta: string): Comparacion;
+/** ¿Cumple el criterio? En las DOS direcciones Y encajando en la pantalla: cada borde del contenido cerca del de la maqueta. */
+export declare function cumpleElCriterio(c: Pick<Comparacion, "distanciaVertical" | "distanciaHorizontal" | "encaje">): boolean;
+/** La cifra corta, para el informe al orquestador. */
+export declare function resumenDeMedida(c: Pick<Comparacion, "distanciaVertical" | "distanciaHorizontal" | "encaje">, captura: string): string;
+/** El mensaje para quien llamó a quien ejecuta. `pedirCritica`: no ha pasado el crítico desde su última escritura. */
+export declare function textoDeMedidaAutomatica(opciones: {
+    quien: string;
+    captura: string;
+    maqueta: string;
+    comparacion: Comparacion;
+    pedirCritica: boolean;
+    /** Qué ronda visual es esta para quien la recibe (1, 2…). Ausente: no se cuenta. */
+    ronda?: number;
+}): string;

package/dist/agent/motores/trueforge/memoriaDeEspecialistas.d.ts

@@ -0,0 +1,60 @@
+/** Hasta aquí se guarda el historial ENTERO. Provisional: el orden de un conductor o un consultor. */
+export declare const TOPE_COMPLETA_TOKENS = 48000;
+/** Hasta aquí se guarda REDUCIDO; por encima se olvida. Provisional. */
+export declare const TOPE_REDUCIDA_TOKENS = 40000;
+/** Lo que se conserva de lo que devolvió cada tool en la versión reducida. */
+export declare const MAX_CARACTERES_DE_RESULTADO = 500;
+/** A partir de cuántos caracteres un argumento de una llamada a tool (el contenido de un `write_file`, el texto de un `edit_file`) hace que esa llamada se CUENTE en vez de guardarse (`reducirHistorial`). */
+export declare const MAX_CARACTERES_DE_ARGUMENTO = 300;
+/**
+ * Los ENCARGOS que un especialista hizo a otro (`create_sub_agent`) se conservan enteros hasta aquí. Son cortos y son
+ * lo que necesita recordar; y recortados le enseñaban a cortar los nuevos (ver `reducirHistorial`).
+ */
+export declare const MAX_CARACTERES_DE_ENCARGO = 8000;
+/**
+ * El historial sin lo voluminoso: lo que devolvió cada tool se recorta (con la marca de que se recortó, para
+ * que el modelo sepa que puede releerlo), los argumentos largos de sus llamadas también, y el razonamiento de
+ * las vueltas viejas se quita. Lo que el especialista DIJO y a qué fichero o búsqueda apuntó cada llamada se
+ * conservan. Puro.
+ */
+export declare function reducirHistorial(mensajes: readonly unknown[], maxResultado?: number, maxArgumento?: number): unknown[];
+/**
+ * La VENTANA: lo más reciente que cabe. Cada delegación empieza con un mensaje de usuario (el encargo o el «NUEVO
+ * ENCARGO»), así que se descartan delegaciones ENTERAS, las más antiguas primero: una llamada a tool y su respuesta
+ * viven dentro de la misma delegación y nunca quedan partidas. Si ni la última cabe sola, se queda con su encargo y
+ * lo último que dijo el especialista, que es lo que contó que había hecho.
+ *
+ * Existe porque en la primera prueba larga «olvidada-por-tope» llegó a borrar la memoria de los cuatro
+ * especialistas que más trabajaban, incluido lo reciente: perder lo viejo es aceptable, perder lo que acaba de
+ * pasar no. Puro.
+ */
+export declare function ventanaDeHistorial(mensajes: readonly unknown[], topeTokens: number): unknown[];
+export interface EncarnacionPrevia {
+    /** Los mensajes con los que arranca el hijo nuevo, ya saneados. */
+    mensajes: unknown[];
+    tokens: number;
+}
+/** Por qué una encarnación arranca sin memoria, para la traza. */
+export type SinMemoria = "primera" | "hilo-vivo" | "olvidada-por-tope" | "olvidada-por-fallo";
+export interface MemoriaDeEspecialistas {
+    /** Abre una encarnación de `nombre`: su memoria si la hay y se puede usar, o el motivo de no. */
+    abrir(nombre: string, hilo: string): {
+        previa: EncarnacionPrevia;
+    } | {
+        sin: SinMemoria;
+    };
+    /** La encarnación `hilo` terminó: guarda su historial completo (o lo olvida si falló o pasó el tope). */
+    cerrar(hilo: string, resultado: {
+        bien: boolean;
+        mensajes: readonly unknown[];
+        tokens: number;
+    }): SinMemoria | "guardada" | "guardada-reducida" | "guardada-ventana";
+    /** Los hilos vivos se dieron por muertos (turno cortado, orquestador rehecho). La memoria se queda. */
+    darPorMuertos(): void;
+    /** Otra conversación: se olvida todo. */
+    olvidar(): void;
+}
+export declare function crearMemoriaDeEspecialistas(topes?: {
+    completa?: number;
+    reducida?: number;
+}): MemoriaDeEspecialistas;

package/dist/agent/motores/trueforge/memoriaTrueforge.d.ts

@@ -0,0 +1,131 @@
+/** Lo que se guarda de un hilo: lo que su constructor sabe recibir de vuelta. */
+export interface FotoDeHilo {
+    context: unknown[];
+    current_context_usage?: unknown;
+    capability_state?: Record<string, unknown> | null;
+    /**
+     * La pregunta del orquestador (`ask_user_question`) que espera respuesta. Va CON la foto porque
+     * sin ella, al reabrir, la respuesta de la persona entraría como un mensaje nuevo y la pregunta
+     * se quedaría saldada como incompleta. Mientras esté, su tool call NO se salda.
+     */
+    pregunta_pendiente?: PreguntaPendiente;
+}
+/** La pregunta en espera: en qué hilo, qué tool call contesta y con qué opciones. */
+export interface PreguntaPendiente {
+    hilo: string;
+    id: string;
+    args: Record<string, unknown>;
+    /** El encargo que provocó la pregunta: sin él, tras reabrir, el juez y la reparación del
+     *  turno de la respuesta no tendrían contra qué medir. Opcional: una v1 anterior no lo trae. */
+    encargo?: string;
+}
+/** Dónde vive la memoria de la sesión `hilo`, o `undefined` si el id no es un segmento llano. */
+export declare function rutaDeMemoria(raiz: string, hilo: string): string | undefined;
+/** El texto con que se salda una tool call que el turno no llegó a contestar. */
+export declare const RESPUESTA_A_UNA_COLGADA: string;
+/**
+ * El texto con que se salda una tool call que una INTERRUPCIÓN dejó sin respuesta: el proceso se
+ * paró a mitad de turno (un corte duro, sin cierre ordenado) y la foto que se reabre es la que se
+ * guardó A MITAD. No puede ser `RESPUESTA_A_UNA_COLGADA`: su «vuelve a pedirlo» invita a repetir
+ * un encargo cuyo especialista ya pudo dejar ediciones en el disco, y repetirlo las duplicaría.
+ * Lo escrito es «al menos»: se cuenta por hilo y un nieto que ya devolvió no siempre consta.
+ */
+export declare function textoDeInterrupcion(llamada: {
+    especialista?: string;
+    escritos: readonly string[];
+}): string;
+/**
+ * El contexto con las tool calls del ÚLTIMO mensaje del asistente que no tienen respuesta,
+ * saldadas. Solo el último: una anterior sin respuesta ya habría roto la conversación antes.
+ * Puro: no toca el contexto que recibe. `textoDe` da el texto de cada una (por omisión,
+ * `RESPUESTA_A_UNA_COLGADA`): la foto a mitad de turno salda con el de una interrupción.
+ */
+export declare function saldarColgadas(context: readonly unknown[], excepto?: string, textoDe?: (id: string, nombre: string | undefined) => string): unknown[];
+/** La foto lista para guardar o para rehacer el hilo: con las colgadas saldadas. */
+export declare function fotoSaneada(foto: FotoDeHilo): FotoDeHilo;
+/**
+ * La versión del formato de la foto en disco. Sube cuando cambia lo que se escribe, y cada subida
+ * trae su entrada en `MIGRACIONES`: una foto de antes se MIGRA al leerla, nunca se descarta por
+ * vieja. Es NUESTRA, no la de la librería: la de la librería va aparte, en `trueforge`.
+ *
+ * El formato v1, entero —y nada más, que es lo que hace estricta la lectura—:
+ *
+ * ```json
+ * { "version": 1, "trueforge": "0.2.1", "context": [...],
+ *   "current_context_usage": {...}, "capability_state": {...} | null,
+ *   "pregunta_pendiente": { "hilo": "...", "id": "...", "args": {...}, "encargo"?: "..." } }
+ * ```
+ *
+ * Solo `version` y `context` son obligatorios. `trueforge` es la versión de la librería que
+ * escribió el `toSnapshot()`: se APUNTA, no se exige —rechazar por ella tiraría todas las
+ * conversaciones en cada subida de la librería—, y está para que una migración futura sepa de
+ * dónde parte. Falta en una foto MIGRADA desde v0, porque no se inventa lo que no consta; el
+ * guardado siguiente la sella.
+ */
+export declare const VERSION_DE_MEMORIA = 1;
+/** Lo que se lee de disco antes de entenderlo: un objeto JSON cualquiera. */
+type FotoCruda = Record<string, unknown>;
+/**
+ * De cada versión a la SIGUIENTE: devuelve la foto migrada o el MOTIVO por el que no se puede.
+ * Puras, y se encadenan (`interpretarFoto`), así que una foto de hace tres versiones pasa por
+ * las tres. Una migración no valida el resultado final: eso lo hace UNA vez `validarV1`.
+ */
+export declare const MIGRACIONES: Readonly<Record<number, (foto: FotoCruda) => FotoCruda | string>>;
+/** Lo que devuelve leer la memoria: no hay, se entiende, o hay y no se entiende (con el porqué). */
+export type LecturaDeMemoria = {
+    estado: "sin-memoria";
+} | {
+    estado: "ok";
+    foto: FotoDeHilo;
+} | {
+    estado: "incompatible";
+    motivo: string;
+};
+/**
+ * El TEXTO de una foto, entendido: migrado hasta la versión actual y validado, o el motivo por el
+ * que no. Pura, y es toda la regla de la lectura. El motivo nunca repite el contenido —un error de
+ * `JSON.parse` cita un trozo del fichero, que lleva mensajes enteros— ni ninguna ruta.
+ */
+export declare function interpretarFoto(texto: string): Exclude<LecturaDeMemoria, {
+    estado: "sin-memoria";
+}>;
+/**
+ * Escribe la foto, en el formato ACTUAL: la versión y la de la librería las SELLA aquí quien
+ * escribe, no quien llama, y los campos van por lista cerrada —lo que `toSnapshot()` traiga de más
+ * no llega a disco, y así la lectura estricta no rechaza lo que este mismo código escribió—.
+ * El fichero se CREA con 0600 antes de tener contenido y se reemplaza con `renameSync`, para que
+ * un corte a mitad no deje media conversación ni un JSON roto.
+ */
+export declare function guardarMemoria(raiz: string, hilo: string, foto: FotoDeHilo): void;
+/**
+ * La memoria de la sesión, con su estado. No tener fichero es `sin-memoria`, no un fallo; uno que
+ * existe y no se puede leer es `incompatible` con el `code` de Node y nada más (su mensaje lleva
+ * la ruta absoluta). NO aparta ni borra nada: esto lo llama también quien solo PREGUNTA
+ * (`hayMemoria`, la web al reabrir), y preguntar no puede mover ficheros.
+ */
+export declare function cargarMemoria(raiz: string, hilo: string): LecturaDeMemoria;
+/** La foto guardada y entendida, o `undefined` si no hay o no se entiende (ver `cargarMemoria`). */
+export declare function leerMemoria(raiz: string, hilo: string): FotoDeHilo | undefined;
+/**
+ * ¿Hay una conversación de TrueForge que continuar en esta sesión? Solo si la foto se ENTIENDE:
+ * una incompatible no se va a cargar, y decir que sí haría que la web presentara como continuada
+ * una sesión que empieza de cero.
+ */
+export declare function hayMemoria(raiz: string, hilo: string): boolean;
+/**
+ * Aparta la foto que no se entiende, con otro nombre y en la MISMA carpeta, y devuelve ese nombre
+ * (solo el nombre: viaja a la pantalla). Apartar y no borrar, porque no la entendemos y puede que
+ * un XOneCode más nuevo sí; y apartar y no dejarla, porque el guardado del primer turno la pisaría.
+ * Un nombre que ya existe nunca se pisa. Si no se puede, devuelve `undefined` y quien llama lo
+ * DICE: la foto se queda donde estaba y el siguiente guardado la sustituirá.
+ */
+export declare function apartarMemoria(raiz: string, hilo: string, ahora?: number): string | undefined;
+/**
+ * El aviso de una memoria que no se cargó, con el motivo y con lo que se hizo con la foto. Se
+ * emite UNA vez, en el primer turno: es cuando importa, porque es el turno en que el modelo no
+ * recuerda lo que la pantalla enseña. Solo con una foto que EXISTÍA: sin foto no ha pasado nada.
+ */
+export declare function textoDeMemoriaDescartada(motivo: string, apartada: string | undefined): string;
+/** Borra la memoria de la sesión, las fotos apartadas incluidas: lo llama el borrado de una sesión. */
+export declare function olvidarMemoria(raiz: string, hilo: string): void;
+export {};

package/dist/agent/motores/trueforge/metricasTrueforge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Las métricas PROPIAS de TrueForge (`AgentThreadOrchestrator.getMetrics()`), puestas al lado de
+ * las nuestras como CONTRASTE, no como sustituto.
+ *
+ * Las nuestras salen de traducir cada evento (`eventosTrueforge.ts#traducirEvento`) y son las que
+ * se enseñan y se guardan, porque son las mismas cuentas que las de deepagents. Las de la librería
+ * las lleva ella por dentro. Si las dos divergen, una de las dos cuenta mal, y hasta ahora no había
+ * forma de enterarse: esto lo apunta en la traza (`XONECODE_TRACE_TOOLS=1`) y `xonecode traza` lo
+ * dice. Puro, para poder probar la regla sin montar un turno.
+ *
+ * Se lee al final de CADA turno y es de ESE turno: el raíz se rehace desde su foto al acabar
+ * (`sesionTrueforge.ts`), así que el árbol que se mide es el de un solo turno.
+ */
+/** Lo que dice NUESTRA cuenta de un turno: el delta del tracker. */
+export interface CifrasDelTurno {
+    entrada: number;
+    salida: number;
+    cache: number;
+    llamadas: number;
+}
+/** Lo que dice la de TrueForge, con los nombres nuestros. Ausente = la librería no lo trae. */
+export interface MetricasDeTrueforge {
+    entrada: number;
+    salida: number;
+    cache?: number;
+    iteraciones: number;
+    tools: number;
+    subagentes: number;
+    resumenes: number;
+    costeUsd?: number;
+}
+/** De la forma de la librería (`AgentThreadMetrics`) a la nuestra; lo que no es número no consta. */
+export declare function metricasDeTrueforge(m: Record<string, unknown>): MetricasDeTrueforge;
+/**
+ * En qué difieren, dicho con las dos cifras. Vacío = coinciden.
+ *
+ * Los TOKENS se comparan tal cual: los dos lados suman el mismo `usage` de cada llamada, así que
+ * cualquier diferencia es una cuenta que se pierde en uno de ellos. Las LLAMADAS no se cuentan
+ * igual, y las dos diferencias están MEDIDAS contra la librería real: un hijo EXTERNO es una
+ * iteración para ella y cero llamadas para nosotros —su gasto es del producto, en la cuenta
+ * `externo`—; y una COMPACTACIÓN es una llamada para nosotros —se paga— y para ella no es una
+ * iteración, la lleva aparte en `resumenes`. Las dos se ajustan antes de comparar. Y la caché solo
+ * si la librería la trae: ausente no es cero.
+ */
+export declare function diferenciasDelContraste(nuestras: CifrasDelTurno, suyas: MetricasDeTrueforge, hijosExternos: number): string[];

package/dist/agent/motores/trueforge/modeloExterno.d.ts

@@ -0,0 +1,9 @@
+import type { PeticionExterna, SubagenteExternoPort } from "../../../core/ports.js";
+import type { ILLM } from "./trueforge.js";
+export declare function modeloExternoParaTrueforge(opciones: {
+    puerto: SubagenteExternoPort;
+    /** La petición entera menos la señal, compuesta al DELEGAR (instrucciones e inventario frescos). */
+    peticion: () => Omit<PeticionExterna, "senal">;
+    /** La cancelación del turno: se le pasa al producto para que no quede un proceso vivo. */
+    senal?: () => AbortSignal | undefined;
+}): ILLM;

package/dist/agent/motores/trueforge/modeloLangchain.d.ts

@@ -0,0 +1,69 @@
+/**
+ * El modelo de TrueForge (`ILLM`) hecho con NUESTRO modelo de LangChain.
+ *
+ * TrueForge trae su propio cliente (`VercelAILLM`), que construye el modelo desde una
+ * configuración de proveedor. No se usa, y es la decisión que hace el motor intercambiable sin
+ * que se note: nuestros modelos salen de `Modelos.paraPapel()` ya con todo lo que se les ha ido
+ * poniendo —el `user_id` de DeepSeek, el eco de su razonamiento, el tope de salida y el
+ * pensamiento adaptativo de Claude, el esfuerzo por modelo—, y reconstruirlos con la
+ * configuración de TrueForge lo perdería todo en silencio.
+ *
+ * El contrato de TrueForge habla en la forma de las chat completions de OpenAI, así que esto es
+ * una traducción en los dos sentidos: los mensajes que manda a mensajes de LangChain, y el stream
+ * de LangChain a los fragmentos que espera.
+ *
+ * **La cancelación entra por aquí**: `ILLM.create` no recibe señal, así que la de la llamada en
+ * curso se pide a `senal()` en cada `create`, y quien corre el turno la pone.
+ */
+import { type BaseMessage } from "@langchain/core/messages";
+import type { ILLM } from "./trueforge.js";
+type MensajeOpenAi = {
+    role: string;
+    content?: unknown;
+    tool_calls?: {
+        id: string;
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    tool_call_id?: string;
+    reasoning_content?: string;
+};
+/** Los mensajes que manda TrueForge, en mensajes de LangChain. */
+export declare function aMensajesDeLangchain(mensajes: readonly MensajeOpenAi[]): BaseMessage[];
+/**
+ * Un `ILLM` sobre un modelo de LangChain. `modelo` y `senal` son funciones y no valores: el modelo
+ * cambia con `/modelo` sin rehacer el hilo, y la señal es la de la llamada EN CURSO.
+ */
+export declare function modeloParaTrueforge(opciones: {
+    modelo: () => unknown;
+    senal?: () => AbortSignal | undefined;
+    nombre?: string;
+    /**
+     * DETENER (`detencion.ts`): mientras devuelva un texto, la respuesta NO lleva tool calls —se
+     * tiran del stream y del mensaje final— y, si no queda texto, lleva ése. Una respuesta sin tool
+     * calls cierra el hilo. Se pregunta en cada llamada.
+     */
+    soloTexto?: () => string | undefined;
+    /** Cuántas tool calls se tiraron por `soloTexto`: la medida de si el filtro hace falta. */
+    alTirarLlamadas?: (cuantas: number) => void;
+    /**
+     * DETENER a MITAD de una llamada: la señal que corta SOLO el stream de este hijo —no el turno—
+     * y la orden con la que se le pide el resumen. Si se aborta mientras genera, la llamada no
+     * falla: se relanza en el acto con lo que ya había dicho y la orden al final, sin tool calls, y
+     * a la librería le llega UNA respuesta normal de texto —que cierra el hilo—. Se pregunta al
+     * empezar cada llamada; con `soloTexto` ya activo no hace falta (la orden llegó antes).
+     */
+    corte?: () => {
+        senal: AbortSignal;
+        orden: () => string;
+    } | undefined;
+    /**
+     * Cuántos de los tokens de salida de una llamada fueron RAZONAMIENTO. La librería reconstruye el
+     * uso de sus eventos sin ese campo, así que se avisa aquí, a la salida del adaptador, con los
+     * tokens de salida para emparejarlo con el evento.
+     */
+    alRazonar?: (salida: number, razonamiento: number) => void;
+}): ILLM;
+export {};

package/dist/agent/motores/trueforge/notas.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Una nota escrita mientras el agente trabaja (IXCODE-4), con UN dueño.
+ *
+ * Se entregaba a CADA hilo como encargo, y eso se midió con una prueba real (MyAllXOne): «y créame
+ * un diagrama» llegó al analista, que lo dibujó, y al volver el orquestador la recibió igual de
+ * nueva y se lo encargó otra vez a `designer-xone` — el diagrama, dos veces. La regla ahora:
+ *
+ * - **Si trabaja UN solo hijo, la nota es suya**: la incorpora si le cabe en el encargo, y si no, la
+ *   devuelve como pendiente (`textoDeNotaParaHijo`).
+ * - **Con VARIOS en paralelo no es de ninguno**: dársela a uno sería una carrera, y a todos es el
+ *   bug de arriba. La decide el raíz al volver, como encargo.
+ * - **Sin hijos trabajando, es del raíz**, que es quien planifica.
+ * - **El raíz la ve SIEMPRE**, y si ya tenía dueño la ve como INFORMACIÓN: a quién se le pasó y que
+ *   no la vuelva a encargar (`textoDeNotaYaEntregada`).
+ * - Un hijo nacido cuando la nota ya tiene dueño —o ya la vio el raíz— no la recibe: el raíz la
+ *   tiene en cuenta al delegar.
+ *
+ * «Trabajan a la vez» = los hijos nacidos de la última llamada del raíz: mientras un hijo vive, el
+ * raíz espera su resultado y no llama al modelo (`detencion.ts#hijosVivos`). Un hijo EXTERNO no
+ * pasa por los procesadores, así que nunca se la queda: la recoge el raíz.
+ */
+export interface Nota {
+    texto: string;
+    /** `thread_id` de quien se la quedó como encargo. Ausente: todavía de nadie. */
+    duenio?: string;
+    vistaPorElRaiz: boolean;
+}
+export declare function crearNota(texto: string): Nota;
+/** Lo que hace falta saber del árbol en el momento de entregar. */
+export interface ContextoDeEntrega {
+    hiloRaiz: string;
+    /** Cuántos hijos trabajan a la vez ahora mismo. */
+    hijosVivos: number;
+    /** El nombre con que el raíz conoce a un hilo hijo (su especialista). */
+    nombreDe: (threadId: string) => string;
+}
+/** Para el raíz: lo que la persona le dijo. */
+export declare function textoDeNota(texto: string): string;
+/** Para un hijo: su interlocutor normal es quien le delegó, así que se dice que viene de fuera, y
+ *  se le da la salida si no es de su encargo. */
+export declare function textoDeNotaParaHijo(texto: string): string;
+/** Para el raíz, cuando la nota ya se la quedó un hijo. */
+export declare function textoDeNotaYaEntregada(texto: string, quien: string): string;
+/** Los textos que se le meten a ESE hilo antes de su llamada, marcando lo entregado. */
+export declare function entregarNotas(notas: readonly Nota[], threadId: string, ctx: ContextoDeEntrega): string[];
+/** Lo que NADIE se quedó, para mandarlo como el turno siguiente. `undefined` si no queda ninguna —
+ *  así el llamador no confunde "sin sobrantes" con una cadena vacía. */
+export declare function sobrantes(notas: readonly Nota[]): string | undefined;

package/dist/agent/motores/trueforge/proponerTareas.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { NOMBRE_PROPONER_TAREAS, type PropuestaDeTareas } from "../../../core/repartoDeEncargo.js";
+export { NOMBRE_PROPONER_TAREAS };
+export declare function crearProponerTareas(proponer: (p: PropuestaDeTareas) => void): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    motivo: z.ZodString;
+    tareas: z.ZodArray<z.ZodObject<{
+        titulo: z.ZodString;
+        peticion: z.ZodString;
+        adjuntos: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, {
+    motivo: string;
+    tareas: {
+        titulo: string;
+        peticion: string;
+        adjuntos?: string[] | undefined;
+    }[];
+}, {
+    motivo: string;
+    tareas: {
+        titulo: string;
+        peticion: string;
+        adjuntos?: string[] | undefined;
+    }[];
+}, string, unknown, "proponer_tareas">;
+/**
+ * Lo que el raíz sabe de `proponer_tareas`, solo cuando la tiene. Preguntar ANTES es petición de la persona: la tarea no
+ * verá esta conversación, así que lo que falte en su encargo lo adivinaría.
+ */
+export declare const REPARTIR_EN_TAREAS: string;