xonecode 0.38.44 → 0.39.2

package/dist/agent/turno/inspectorDePrompt.d.ts

@@ -0,0 +1,150 @@
+/**
+ * El INSPECTOR: qué entra de verdad al modelo en cada llamada.
+ *
+ * Todo lo que se ha medido en este harness hasta ahora era lo que SALE —tokens contados por el
+ * proveedor, tools llamadas, ficheros leídos—, y de ahí se DEDUCÍA lo que entra. Eso llegó
+ * lejos, pero se quedó corto dos veces el mismo día: cuando un especialista perdió su encargo en
+ * el resumen hubo que reconstruirlo leyendo la fuente de la librería, y cuando el chat empezó a
+ * enseñar ficheros enteros hubo que adivinar por dónde se colaban. Con esto se mira.
+ *
+ * Es un `wrapModelCall`, o sea el último sitio antes de que la petición salga: lo que ve es
+ * exactamente lo que el modelo va a recibir, después de TODOS los middleware —el resumen, la
+ * devolución del encargo, la conversión de los `ToolMessage`— y no lo que alguien creía haber
+ * puesto.
+ *
+ * ## Dos niveles, y el de por omisión no lleva contenido
+ *
+ * - `XONECODE_TRACE_PROMPT=1` apunta la FORMA: origen, cuántos mensajes, de qué tipo, cuánto
+ *   ocupa cada uno, el tamaño del prompt de sistema y cuántas tools van declaradas. Con eso se
+ *   contesta la pregunta cara —a dónde se va el contexto— sin sacar a disco una línea del
+ *   proyecto.
+ * - `XONECODE_TRACE_PROMPT=todo` añade el TEXTO. Es lo que hace falta para ver por qué un
+ *   agente contesta lo que contesta, y por eso existe; pero saca a disco el contenido de lo que
+ *   se haya leído, así que se pide aparte y a sabiendas. Es la misma disciplina que
+ *   `diagnosticoDeTools.ts`, que nunca guarda contenido: aquí el contenido ES la pregunta, así
+ *   que no se puede prohibir — se puede hacer explícito.
+ *
+ * El fichero vive en `.xonecode/`, que está denegada al agente, fuera de git y fuera de lo que
+ * sube a CloudStudio.
+ */
+import { createMiddleware } from "langchain";
+export declare const VARIABLE_TRAZA_PROMPT = "XONECODE_TRACE_PROMPT";
+export declare const NOMBRE_TRAZA_PROMPT = "traza-prompt.jsonl";
+/** Ruta pública, solo para poder decirle a alguien dónde quedó su diagnóstico. */
+export declare function rutaTrazaDePrompt(raiz: string): string;
+/** Qué se apunta de cada mensaje. El `texto` solo con el nivel `todo`. */
+export interface MensajeInspeccionado {
+    tipo: string;
+    caracteres: number;
+    /** Cuántas tool calls pide, si pide alguna. Ausente si ninguna. */
+    toolCalls?: number;
+    texto?: string;
+}
+/** Una tool declarada: su nombre y lo que ocupa su esquema. */
+export interface EsquemaInspeccionado {
+    nombre: string;
+    caracteres: number;
+}
+export interface LlamadaInspeccionada {
+    origen: string;
+    mensajes: MensajeInspeccionado[];
+    sistema: {
+        caracteres: number;
+        texto?: string;
+    };
+    tools: number;
+    /**
+     * Lo que ocupan los ESQUEMAS de las tools, que es la mitad que faltaba.
+     *
+     * Medido el 17-09-2026 con la primera versión de esto: el inspector decía 8.151 caracteres
+     * —unos 2k tokens— en la última llamada de un turno que pagó 3.900 tokens por llamada. La
+     * diferencia eran los esquemas, que se reenvían ENTEROS en cada petición y aquí se contaban
+     * como un número («tools: 8») en vez de como tamaño. Es lo mismo que documenta el harness de
+     * deepseek: «schema tokens repeat on every request; restricting a tool removes its entire
+     * schema cost for that agent».
+     */
+    esquemas: {
+        caracteres: number;
+        porTool: EsquemaInspeccionado[];
+    };
+    /**
+     * La HUELLA de lo que va delante: el prompt de sistema y los esquemas, en su orden.
+     *
+     * Es lo que decide si la caché de un proveedor puede enganchar, porque toda caché de prompt
+     * es por PREFIJO: si esto cambia entre dos llamadas, aunque sea por el orden de las tools o
+     * por una descripción generada, la reutilización se rompe desde el primer byte distinto. Y se
+     * contesta con un hash en vez de con el texto, así que la pregunta se puede responder sin
+     * sacar una línea del proyecto a disco.
+     */
+    prefijo: {
+        caracteres: number;
+        huella: string;
+    };
+    /** La suma de TODO lo que va en la petición: sistema, mensajes y esquemas. */
+    caracteresTotales: number;
+    /**
+     * Lo que el PROVEEDOR dice que costó esa misma llamada.
+     *
+     * Es la otra mitad, y va en la MISMA línea a propósito: el inspector cuenta caracteres y la
+     * factura viene en tokens, así que separarlos obliga a cruzar dos ficheros a ojo para
+     * contestar «¿de dónde salió esta cifra?». Juntos, una línea dice lo que entró y lo que
+     * costó. La primera medida con esto puesto habría enseñado de golpe que los esquemas eran el
+     * 80 % del turno, en vez de deducirlo restando.
+     *
+     * Ausente cuando el proveedor no lo manda: un cero aquí sería una medición que nadie hizo.
+     */
+    uso?: {
+        entrada: number;
+        salida: number;
+        cache: number;
+    };
+}
+/**
+ * Lo que ocupa el esquema de una tool, tal y como viaja.
+ *
+ * Se serializa lo que la librería expone —nombre, descripción y esquema de parámetros— porque
+ * una tool de LangChain no publica su forma de red. Es una ESTIMACIÓN y se dice: sirve para
+ * comparar unas tools con otras y para ver cuánto pesa la cabecera, no para cuadrar con la
+ * factura del proveedor.
+ */
+/**
+ * El esquema de una tool como TEXTO: nombre, descripción y parámetros.
+ *
+ * Es lo que se mide y lo que se huele, y tiene que ser el CONTENIDO y no un resumen: la primera
+ * versión hacía la huella sobre `{nombre, caracteres}`, o sea sobre la propia medida, y entonces
+ * una descripción que cambiara conservando el largo habría dado la misma huella. Una huella que
+ * no cambia cuando cambia lo que representa no vale para nada.
+ */
+export declare function textoDeEsquema(t: unknown): string;
+export declare function esquemaDeTool(t: unknown): EsquemaInspeccionado;
+/** El tipo de un mensaje, venga como venga: langchain no lo expone igual en todos. */
+export declare function tipoDeMensaje(msg: unknown): string;
+/**
+ * El consumo que declara una respuesta del modelo, si lo declara.
+ *
+ * Se mira `usage_metadata` (el estándar de LangChain, que los tres adaptadores que usamos
+ * rellenan) y su `input_token_details.cache_read`. Lo que no venga se queda AUSENTE en vez de
+ * volverse cero: ya hay bastantes ceros inventados en este oficio.
+ */
+export declare function usoDeRespuesta(respuesta: unknown): {
+    entrada: number;
+    salida: number;
+    cache: number;
+} | undefined;
+/** El texto de un mensaje, con los bloques concatenados. Nunca `undefined`. */
+export declare function textoDeMensaje(msg: unknown): string;
+/**
+ * La FOTO de una petición al modelo, sin tocar disco: pura, y por eso con test.
+ *
+ * `conTexto` decide si se lleva el contenido. Separar el cálculo de la escritura es lo que
+ * permite comprobar que la forma es correcta sin montar un agente ni escribir un fichero.
+ */
+export declare function inspeccionarLlamada(origen: string, peticion: unknown, conTexto: boolean): LlamadaInspeccionada;
+/**
+ * El middleware. Devuelve `undefined` si la traza no está pedida, para no montarlo.
+ *
+ * Se pone al FINAL de la lista de cada agente: el primero envuelve al siguiente, así que el
+ * último es el que ve la petición ya pasada por todos los demás — que es justo lo que se quiere
+ * inspeccionar. Puesto delante mentiría enseñando lo que otros van a cambiar después.
+ */
+export declare function inspectorDePrompt(raiz: string, origen: string, entorno?: NodeJS.ProcessEnv): ReturnType<typeof createMiddleware> | undefined;

package/dist/agent/turno/instantanea.d.ts

@@ -0,0 +1,16 @@
+export interface Cambio {
+    /** Ruta relativa al PROYECTO, no al repo: el prefijo ya viene recortado. */
+    ruta: string;
+    clase: "nuevo" | "modificado" | "borrado";
+}
+export interface Instantanea {
+    /** Cómo se tomó. Un deshacer del que no sabes cuál es, no es un deshacer. */
+    via: "git" | "huellas";
+    cambios(): Promise<Cambio[]>;
+    /** El diff con contenido, que es el formato que un modelo lee bien. Vacío sin git. */
+    diff(): Promise<string>;
+}
+export declare function tomarInstantanea(raiz: string, git: {
+    usable: boolean;
+    prefijo: string;
+}): Promise<Instantanea>;

package/dist/agent/turno/interrupts.d.ts

@@ -0,0 +1,54 @@
+import { buildResume, type Decision, type PendingInterrupt } from "../../vendor/hitl.js";
+import type { PendienteDeAprobacion } from "../../core/events.js";
+import { type LineaDeDiff } from "../../core/diff.js";
+export { buildResume, type Decision, type PendingInterrupt };
+/**
+ * Los interrupts pendientes de un hilo, en el vocabulario de xonecode.
+ *
+ * **Se pregunta al ESTADO, no al resultado del stream.** La clave `__interrupt__` solo
+ * existe en la llamada que pausó; el estado sobrevive al proceso y es la fuente de verdad.
+ * Es la misma razón por la que se puede pausar en un proceso y aprobar desde otro.
+ */
+export declare function pendientesDe(agente: unknown, config: unknown): Promise<PendienteDeAprobacion[]>;
+/**
+ * De la forma de deepagents a la de xonecode.
+ *
+ * El `origen` sale de la `description`, que es donde `hitlDe()` metió el nombre del perfil
+ * —`[dev] quiere escribir un fichero del proyecto`—: **el interrupt no dice de qué
+ * subagente viene**, y `dev` y `mockup` comparten `write_file`.
+ *
+ * **Y una vez extraído, el prefijo se QUITA de la descripción.** Las tres pieles pintan los
+ * dos campos, uno debajo del otro (`cli/aprobar.ts`, `cli/tui/aprobarTui.tsx`,
+ * `componentes/Aprobacion.tsx`), así que dejarlo decía lo mismo dos veces pegado: «[dev]
+ * quiere modificar un fichero del proyecto» y justo debajo «quién: dev». Se quita aquí y no
+ * en cada piel porque el dato es uno y el sitio donde vive es `origen` — tres recortes a
+ * mano son tres sitios donde divergir. Sin corchete no hay nada que quitar y la descripción
+ * se queda tal cual: es la de un interrupt que no pasó por `hitlDe` (el `Ejecutar <tool>`
+ * de reserva de `collectPending`), y ahí `origen` es el nombre de la tool.
+ */
+export declare function aPendiente(p: PendingInterrupt): PendienteDeAprobacion;
+/**
+ * Qué fichero se va a tocar, para poder decirlo sin enseñar los argumentos.
+ *
+ * Los argumentos NO se publican: `write_file` lleva el contenido entero. Pero aprobar a
+ * ciegas es peor que no aprobar, así que se extrae **solo la ruta** de la lista blanca de
+ * claves que la llevan.
+ */
+export declare function ficheroDe(p: PendingInterrupt): string | undefined;
+/** El antes y el después de un pendiente, listos para decidir: la ruta y sus líneas de diff. */
+export interface VistaDelCambio {
+    ruta: string;
+    lineas: LineaDeDiff[];
+}
+/**
+ * La vista del cambio que pide un pendiente: el ANTES es el disco (el interrupt para
+ * ANTES de escribir, así que disco == antes) y el DESPUÉS sale de los argumentos.
+ *
+ * Este es el ÚNICO sitio donde el contenido sale de los argumentos, y es a propósito:
+ * la aprobación es el paso donde enseñar el contenido es la REGLA — aprobar a ciegas
+ * es peor que no aprobar. Fuera de aquí, la lista blanca de `resumenDeTool.ts` manda.
+ *
+ * `leer` entra por parámetro (en producción lee del disco; en los tests, un mapa) y
+ * una tool que no es de escritura, o args incompletos, no produce vista — no crash.
+ */
+export declare function cambioDe(p: PendingInterrupt, leer: (ruta: string) => string): VistaDelCambio | undefined;

package/dist/agent/turno/juezDelTurnoConModelo.d.ts

@@ -0,0 +1,26 @@
+import { type HechosDelTurno, type VeredictoDelTurno } from "../../core/juezDelTurno.js";
+import type { ModelosPort } from "../../core/ports.js";
+/**
+ * El juez del turno cableado a un modelo de verdad.
+ *
+ * Reusa `invocarConModelos` y `PAPEL_DEL_JUEZ` del juez de TAREAS en vez de repetirlos: es
+ * la misma pregunta con otro alcance —«¿esto cumple lo que se pidió?»— y el papel `afilado`
+ * está reservado justo para eso. Dos caminos para invocar al juez serían dos sitios donde
+ * elegir el modelo, y ya pasó con las cuatro copias de `VARIABLES_POR_PROVEEDOR`.
+ *
+ * **Lo caro de este juez es lo que NO se le manda.** Ve el objetivo, la respuesta y cuatro
+ * hechos medidos; nunca el contenido de un fichero ni el transcript. Por eso una llamada
+ * suya cuesta del orden de unos cientos de tokens contra los cientos de miles de un turno,
+ * y puede correr en todos sin que se note en la cuenta.
+ *
+ * **Un fallo suyo NO lanza**: devuelve `dudoso` con el motivo. Es una opinión sobre trabajo
+ * que ya está hecho, y el turno lo trata como tal — `turnoReal.ts` también tiene su `catch`,
+ * porque un juez que se cae no puede llevarse por delante lo que el turno logró. Aquí se
+ * prefiere el veredicto degradado al throw: así el aviso dice «no está claro» en vez de
+ * «no se pudo consultar», que es más honesto sobre lo que le pasa a quien lee.
+ */
+export declare function crearJuezDelTurno(modelos: ModelosPort): (caso: {
+    objetivo: string;
+    respuesta: string;
+    hechos: HechosDelTurno;
+}) => Promise<VeredictoDelTurno>;

package/dist/agent/turno/mensajes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decide si un trozo de `messages` se pinta, y si abre una línea nueva.
+ *
+ * Dos cosas distintas que el modo `messages` mezcla:
+ *  - los TROZOS del LLM, que comparten el `id` del run;
+ *  - los mensajes ENTEROS que un nodo añade al estado, con id propio.
+ *
+ * Un id ya visto y completo es una reemisión: se descarta. Un id distinto del que está
+ * abierto es un mensaje nuevo, y quien pinta tiene que cerrar la línea anterior.
+ */
+export interface Decision {
+    pintar: boolean;
+    /** Cierra la línea abierta antes de pintar: es otro mensaje, no un trozo más. */
+    cierraLinea: boolean;
+}
+export declare class Mensajes {
+    private abierto;
+    private readonly cerrados;
+    /** `texto` vacío o `undefined` no pinta: Gemini manda trozos finales sin texto. */
+    trozo(id: string | undefined, texto: string | undefined): Decision;
+    /** Fin del turno: lo abierto se da por cerrado. */
+    fin(): void;
+}

package/dist/agent/turno/normalizar.d.ts

@@ -0,0 +1,15 @@
+/**
+ * De la forma cruda del stream de langgraph a una sola forma.
+ *
+ * La forma depende de `subgraphs` (medido contra langgraph 1.4.8, ver
+ * `formaDelChunk.test.ts`), y el fallo de leerla mal es MUDO: no lanza, simplemente deja
+ * de casar y no se pinta nada. Por eso se normaliza aquí y nadie más arriba ve la
+ * diferencia — activar o desactivar la bandera deja de ser un cambio con radio.
+ */
+export interface ChunkNormalizado {
+    /** Namespace del subgrafo. Vacío = el grafo padre. */
+    ns: string[];
+    modo: string;
+    dato: unknown;
+}
+export declare function normalizar(chunk: unknown): ChunkNormalizado | null;

package/dist/agent/turno/puente.d.ts

@@ -0,0 +1,196 @@
+import { type ParametrosSeguros } from "./resumenDeTool.js";
+import type { DomainEvent, PendienteDeAprobacion } from "../../core/events.js";
+/** El texto de un mensaje, venga como venga. */
+export declare function textoDe(msg: unknown): string;
+/**
+ * El RAZONAMIENTO de un mensaje, cuando el proveedor lo publica en bloques.
+ *
+ * Gemini lo manda como `{ type: "thinking", thinking: "…" }` dentro de `content`
+ * (`@langchain/google-genai`, `common.js`), o sea que `textoDe` —que solo mira `b.text`— lo
+ * dejaba fuera. Estaba bien dejarlo fuera de la RESPUESTA; lo que faltaba era tener por
+ * dónde enseñarlo aparte.
+ *
+ * Se aceptan las dos formas que hay sueltas por el ecosistema: el bloque `thinking` con su
+ * campo homónimo y el `{ text, thought: true }` que usan otros adaptadores.
+ */
+/**
+ * El razonamiento que se ENSEÑA: el de `razonamientoDe` más el que un cliente compatible con
+ * OpenAI deja en `additional_kwargs.reasoning_content` —DeepSeek, por `@langchain/openai`—, que
+ * no viaja en bloques y por eso no se veía nunca.
+ *
+ * **Es solo para pintar**, y por eso es otra función y no un caso más de la de arriba: la de
+ * arriba también decide qué razonamiento se GUARDA en la memoria de un hilo de TrueForge
+ * (`modeloLangchain.ts`), y el de DeepSeek no entra ahí — su eco lo repone el `fetch`
+ * (`ecoDeRazonamiento.ts`), y meterlo en la foto de la sesión la engordaría para nada.
+ */
+export declare function razonamientoVisibleDe(msg: unknown): string;
+export declare function razonamientoDe(msg: unknown): string;
+/**
+ * Los nombres de tool de un chunk de `updates`, con su detalle de la lista blanca y su ID.
+ *
+ * **El `id` viaja porque el mismo chunk trae la historia ENTERA.** Un `updates` de un subgrafo
+ * no llega con los mensajes nuevos: llega con los acumulados, así que sin distinguir cuáles ya
+ * se contaron, cada paso reemite todas las tools anteriores. Medido sobre un turno real: 286
+ * eventos `execute` para **10 comandos distintos**, con el primero repetido 43 veces — y eso
+ * se ve en la PANTALLA, en tramos repetidos, además de inflar la traza y el contador de pasos.
+ *
+ * El `id` de un `tool_call` es identidad, no parecido: dos llamadas idénticas a la misma tool
+ * con los mismos argumentos son dos llamadas, y colapsarlas por su contenido escondería trabajo
+ * de verdad. Por eso se deduplica por ahí y no por el par nombre+argumentos.
+ */
+export declare function toolsDe(dato: unknown): Array<{
+    nombre: string;
+    detalle?: string;
+    parametros?: ParametrosSeguros;
+    id?: string;
+    respuesta?: string;
+}>;
+/**
+ * Lo que cada tool DEVOLVIÓ, medido en caracteres, por el id de su llamada.
+ *
+ * **Contar llamadas no dice a dónde van los tokens.** Un `read_file` y otro `read_file` son
+ * una linea igual en la traza y pueden ser doscientos caracteres o veinte mil: lo que se paga
+ * es lo que ENTRA en el contexto, no cuántas veces se pidió. Sin esto, la pregunta «¿que me
+ * esta costando este turno?» solo se podía contestar por eliminación.
+ *
+ * **Van los CARACTERES, nunca el contenido** —la misma regla que `core/events.ts`: el
+ * resultado de un `read_file` es el fichero entero y el de una tool MCP lleva el bearer—. Un
+ * tamaño no es contenido, y es lo único que hace falta para repartir el gasto.
+ *
+ * No se convierte a tokens: la razón caracteres/token cambia con el modelo y con lo que haya
+ * dentro, así que dar una cifra de tokens aquí sería inventarse una precisión que no se tiene.
+ */
+export declare function resultadosDe(dato: unknown): Array<{
+    id: string;
+    chars: number;
+}>;
+/**
+ * ¿Este chunk lo emite el grafo PADRE, o un especialista?
+ *
+ * **Medido el 2026-08-30**, sobre un turno real con delegación. Los namespaces que
+ * llegan con `subgraphs: true` son exactamente tres formas:
+ *
+ * | namespace                              | quién         | chunks |
+ * |----------------------------------------|---------------|-------:|
+ * | `["model_request:…"]`                   | el padre      |    148 |
+ * | `["tools:…", "model_request:…"]`        | un especialista |  745 |
+ * | `["tools:…", "tools:…"]`                | tools de un especialista | 12 |
+ *
+ * Un especialista SIEMPRE lleva el segmento `tools:` delante, porque se le invoca con la
+ * tool `task`. Así que la frontera es la LONGITUD.
+ *
+ * **El fallo que esto cierra era mudo y caro.** Antes se descartaba todo `ns` no vacío,
+ * dando por hecho que el padre venía con `ns: []` — cierto para `updates`, FALSO para
+ * `messages`, que llegan con `["model_request:<uuid>"]`. Consecuencia: se descartaban
+ * TODOS los tokens, respuesta incluida. El turno corría entero, enseñaba sus tools,
+ * decía «sin cambios en el proyecto»… y no contestaba nada. Sin excepción y sin aviso.
+ *
+ * Y los números explican por qué el filtro tiene que existir: 745 chunks de especialista
+ * frente a 148 del padre. Emitirlos todos sería volcar el razonamiento interno de los
+ * especialistas encima de la respuesta.
+ */
+export declare function esDelPadre(ns: readonly string[]): boolean;
+/**
+ * El `origen` es EXACTO, no una inferencia, y por eso solo distingue dos.
+ *
+ * Sale de `esDelPadre`, que está medido: un especialista SIEMPRE lleva un segmento `tools:`
+ * delante en su namespace, porque se le invoca con la tool `task`. Lo que el namespace NO dice
+ * es CUÁL especialista — sus segmentos son `tools:<uuid>` y `model_request:<uuid>`, ids opacos.
+ *
+ * **Y se queda así a propósito.** Antes de esto, la única forma de repartir tools por origen era
+ * una heurística sobre el fichero de traza (imputarlas al siguiente registro de modelo), que se
+ * veía que fallaba: daba 21 tools a un especialista cuyo tope son 20. Un número que parece un
+ * dato y es una inferencia es peor que no tenerlo. Esto son dos cubos ciertos en vez de cinco
+ * dudosos, y el que hacía falta —cuánto gasta el orquestador— es uno de los dos.
+ */
+export type OrigenDeTool = "orquestador" | "especialista";
+/**
+ * De quién es esta tool, por el namespace del chunk.
+ *
+ * **No usa `esDelPadre`, y equivocarme con eso costó una medida falsa.** Aquel predicado es la
+ * LONGITUD del namespace y está medido para `messages`, donde el padre llega como
+ * `["model_request:<uuid>"]` — longitud 1. En `updates`, que es el modo por el que llegan los
+ * `tool_calls`, el padre llega con `[]` y un especialista con `["tools:<id>"]`, también
+ * longitud 1. Aplicar allí la regla de la longitud imputaba al orquestador TODAS las tools:
+ * el informe decía «orquestador 70 de 70» en un turno donde un especialista hizo 16 llamadas
+ * y se comió su tope.
+ *
+ * La regla buena es la que el propio comentario de `esDelPadre` ya declaraba: **un
+ * especialista SIEMPRE lleva un segmento `tools:` delante**, porque se le invoca con la tool
+ * `task`. Eso vale en los dos modos y no depende de cuántos segmentos haya.
+ */
+export declare function origenDeTool(ns: readonly string[]): OrigenDeTool;
+export type AlLlamarTool = (tool: {
+    nombre: string;
+    detalle?: string;
+    parametros?: ParametrosSeguros;
+    origen: OrigenDeTool;
+    /** Cuántos caracteres devolvió, si ya se sabe. Ver `alResponderTool`. */
+    chars?: number;
+    /**
+     * Id del MENSAJE del modelo que pidió esta tool. Dos tools con el mismo valor se
+     * pidieron en la MISMA respuesta, que es lo único que decide si van en paralelo.
+     *
+     * Existe porque sin él la traza no podía contestarlo y había que adivinarlo. Medido
+     * sobre un turno real de 69 tools: agrupar por el reloj exacto daba 18 en rafaga (el
+     * milisegundo PARTE una rafaga) y agrupar por los contadores del tracker daba 38, con
+     * dos grupos de 1.000 ms de span, o sea rezagados FUNDIDOS en una respuesta ajena. Dos
+     * metodos, dos respuestas, y ninguno comprobable. Además `origen` solo tiene dos
+     * valores, así que dos especialistas a la vez son indistinguibles: el id del mensaje
+     * tambien los separa.
+     */
+    respuesta?: string;
+}) => void;
+/**
+ * Lo que `aEventos` tiene que recordar ENTRE RONDAS, en un solo sitio.
+ *
+ * **Las tres cosas de aquí dentro vivían sueltas dentro de `aEventos`, y las tres estaban mal
+ * por la misma razón**: `turnoReal.ts` la llama DENTRO del bucle de rondas y el stream
+ * reentrega la historia acumulada al reanudar, así que con estado local cada ronda empezaba en
+ * blanco. Medido dos veces: primero las tools se recontaban, y al arreglar solo aquello se
+ * quedaron mal los resultados —62 medidos para 57 llamadas, con 98.439 caracteres sin
+ * atribuir, el 43 % del total—.
+ *
+ * Van en un objeto y no en tres parámetros porque la razón es UNA —el alcance es el turno— y
+ * porque tres opcionales sueltos son tres sitios donde olvidarse de uno, y ese olvido es mudo.
+ */
+export interface MemoriaDelTurno {
+    /** Los `tool_call` ya contados, por id. */
+    vistas: Set<string>;
+    /** Los resultados ya medidos, por el id de su llamada. */
+    resultados: Set<string>;
+    /** De qué tool era cada llamada, para poder repartir el peso de su resultado. */
+    deQuien: Map<string, {
+        nombre: string;
+        detalle?: string;
+    }>;
+}
+export declare function crearMemoriaDelTurno(): MemoriaDelTurno;
+/**
+ * Lo que una tool devolvió: CUÁNTO pesa, nunca qué era.
+ *
+ * Lleva `nombre` y `detalle` porque un peso suelto no se puede repartir: el id de una llamada
+ * no significa nada en un informe. Salen del `tool_call`, que se procesa ANTES que los
+ * resultados del mismo chunk — **la historia acumulada reentrega los dos JUNTOS**, así que
+ * mirar los resultados primero dejaba sin nombre a todo lo de las rondas siguientes.
+ */
+export type AlResponderTool = (r: {
+    id: string;
+    chars: number;
+    nombre?: string;
+    detalle?: string;
+}) => void;
+/**
+ * Convierte el stream del grafo en `DomainEvent`.
+ *
+ * **Se lee con `subgraphs: true`**, porque sin él lo que hacen los especialistas —que son
+ * grafos compilados invocados dentro de un nodo— no llega al padre, y el fallo es MUDO. El
+ * precio, medido: el chunk pasa de `[modo, dato]` a `[namespace, modo, dato]`, y de eso se
+ * encarga `normalizar`.
+ *
+ * Los tokens que se emiten son SOLO los del grafo padre. Los de un
+ * especialista son su razonamiento interno, no la respuesta: enseñarlos convierte la
+ * consola en un volcado. Su trabajo se cuenta por `tool`, que es lo que el usuario
+ * necesita ver mientras espera.
+ */
+export declare function aEventos(stream: AsyncIterable<unknown>, pendientes?: () => Promise<PendienteDeAprobacion[]>, alLlamarTool?: AlLlamarTool, memoriaDelTurno?: MemoriaDelTurno, alResponderTool?: AlResponderTool): AsyncIterable<DomainEvent>;

package/dist/agent/turno/registroDeFallos.d.ts

@@ -0,0 +1,39 @@
+export declare const NOMBRE_REGISTRO_DE_FALLOS = "fallos.jsonl";
+/**
+ * Cómo se NOMBRA el registro ante quien acaba de ver el error: relativo a la raíz del
+ * proyecto. La ruta absoluta lleva el nombre de la cuenta del sistema y viajaba por el cable
+ * dentro del aviso («Queda apuntado en /Users/…»), y ninguna ruta de la máquina viaja por
+ * ahí; además era la línea que, sin partir, sacaba la barra de scroll horizontal del chat.
+ */
+export declare const RUTA_VISIBLE_DE_FALLOS = ".xonecode/fallos.jsonl";
+/** Dónde queda, para poder decírselo a quien acaba de ver el error. */
+export declare function rutaDeFallos(raiz: string): string;
+export interface RegistroDeFallos {
+    /** Apunta el fallo y devuelve el texto pegable, o `undefined` si no se pudo escribir. */
+    anotar(fallo: {
+        error: unknown;
+        peticion?: string;
+        modelos?: Record<string, string>;
+        pasos?: readonly string[];
+    }): {
+        ruta: string;
+        legible: string;
+    } | undefined;
+}
+/**
+ * El registro de fallos de un proyecto. **Siempre encendido, y ésa es la decisión.**
+ *
+ * La traza de tools es opt-in (`XONECODE_TRACE_TOOLS`) y tiene sentido: se enciende cuando
+ * vas a MEDIR. Esto es lo contrario — un fallo no se planea, y el problema de una bandera
+ * es exactamente que cuando pasó no estaba puesta. Toda la investigación de hoy se hizo
+ * sobre lo que se pudo pegar del chat, con el error truncado y sin saber ni el modelo.
+ *
+ * Se puede permitir estar siempre porque solo escribe cuando algo revienta y lo que
+ * escribe cabe en una pantalla: ni prompts, ni argumentos, ni contenido de ficheros (ver
+ * `core/fallos.ts`). Un turno normal no toca este fichero.
+ *
+ * Síncrono y con el fallo tragado, como la traza: anotar un error no puede provocar otro,
+ * y un `appendFileSync` de trescientos bytes que se pierde si el proceso muere sería justo
+ * el caso en el que hacía falta.
+ */
+export declare function crearRegistroDeFallos(raiz: string, chat?: string | (() => string | undefined)): RegistroDeFallos;