xonecode 0.38.44 → 0.39.2

package/dist/agent/tareas/tareasEnDisco.d.ts

@@ -0,0 +1,141 @@
+import { type AdjuntoDeTarea, type PantallaElegida, type Tarea } from "../../core/tareas.js";
+/** Bytes que se aceptan por adjunto y por tarea. */
+export declare const TOPE_DE_ADJUNTO = 20000000;
+export declare const TOPE_DE_ADJUNTOS_POR_TAREA = 50000000;
+/**
+ * Reescribe las raíces ABSOLUTAS del índice cuando una copia local se ha mudado de sitio.
+ *
+ * Vive aquí y no en quien muda porque el dueño del formato de `indice.json` es este fichero:
+ * un segundo sitio que sepa escribirlo divergiría del primero en cuanto uno de los dos se
+ * corrigiera. Quien llama solo aporta la TRADUCCIÓN (ausente = «esta raíz no la mudé yo»).
+ *
+ * **Se trabaja sobre el JSON crudo**, no sobre `Tarea`: la misma disciplina de
+ * `settingsEnDisco.ts`: pasar por un tipo descartaría en silencio del fichero del usuario
+ * cualquier campo que este proceso no conozca. Y si no hay índice, o no se puede leer, no se
+ * escribe nada: una cola que no está no es una cola rota.
+ *
+ * Devuelve cuántas entradas cambiaron. Cero no escribe el fichero: reescribirlo sin que haya
+ * cambiado nada movería su mtime sin motivo.
+ */
+export declare function remapearRaicesDeTareas(base: string | undefined, traducir: (raiz: string) => string | undefined): number;
+export interface ResultadoDeAdjunto {
+    ok: boolean;
+    /** Una frase, sin ninguna ruta de la máquina. */
+    motivo?: string;
+}
+export interface TareasEnDisco {
+    listar(): Tarea[];
+    guardar(tareas: readonly Tarea[]): void;
+    /** Concede el cerrojo, o dice de quién es. Ver `tomarCerrojo` abajo. */
+    tomarCerrojo(): {
+        tomado: true;
+    } | {
+        tomado: false;
+        dePid: number;
+    };
+    /**
+     * ¿El cerrojo en disco sigue siendo NUESTRO? Hay que preguntarlo antes de cada cosa
+     * consecuente —despachar una tarea—, no solo al tomarlo: `tomarCerrojo` no puede
+     * garantizar por sí solo que no haya dos dueños (ver su comentario), y esto es lo que
+     * hace que el que perdió se entere ANTES de arrancar nada.
+     */
+    sigoSiendoDueño(): boolean;
+    soltarCerrojo(): void;
+    guardarAdjunto(tarea: string, nombre: string, datos: Buffer): ResultadoDeAdjunto;
+    /**
+     * Lo que hay en la carpeta de adjuntos de una tarea, medido del DISCO.
+     *
+     * De aquí sale el `Tarea.adjuntos` que se guarda al crear, y por eso se lee del disco y no
+     * de lo que diga el cliente: el navegador sube los bytes por `POST /adjunto` y después
+     * manda «crear», así que la única fuente que sabe qué llegó de verdad —y cuánto pesa— es
+     * la carpeta. Aceptar la lista del cliente dejaría entrar un adjunto que nadie subió.
+     *
+     * Ordenado por nombre, y solo FICHEROS llanos: una carpeta o un enlace ahí no es un
+     * adjunto, y `readdirSync` los daría igual.
+     */
+    listarAdjuntos(tarea: string): AdjuntoDeTarea[];
+    /**
+     * La carpeta REAL de los adjuntos de una tarea, para montarla en el backend. Se queda en
+     * el host: es una ruta de la máquina.
+     *
+     * `undefined` = **no se puede montar**, y falla cerrado por TIPO para que quien la monte
+     * tenga que decidir qué hacer con eso. Dos casos: un id que no es segmento llano, y una
+     * carpeta cuyo camino REAL se sale de la cola (un enlace simbólico plantado ahí). Que la
+     * carpeta todavía no exista NO es uno de ellos: se crea al escribir el primer adjunto, y
+     * confundir «no hay» con «no vale» dejaría sin montar la carpeta buena.
+     */
+    carpetaDeAdjuntos(tarea: string): string | undefined;
+    borrarTarea(id: string): void;
+}
+export declare function crearTareasEnDisco(opciones: {
+    /** La base (`~/.xonecode` por omisión). Entra por parámetro para probar sin tocar el home. */
+    base?: string;
+    pid?: number;
+    /** ¿Vive ese proceso? Por omisión, `process.kill(pid, 0)`. */
+    vivo?: (pid: number) => boolean;
+    informar?: (texto: string) => void;
+    topeDeAdjunto?: number;
+    topePorTarea?: number;
+    /**
+     * Cómo se APARTA un cerrojo caduco al recogerlo. Por omisión, `renameSync` de verdad.
+     * Entra por parámetro por lo mismo que `vivo`: un test necesita poder provocar que OTRO
+     * proceso gane esa carrera (el `rename` lanzando `ENOENT`), y eso no se puede pedir de
+     * verdad sin dos procesos reales.
+     */
+    renombrar?: (origen: string, destino: string) => void;
+    /**
+     * Cómo se RESTITUYE un cerrojo VIVO que se apartó por error (ver `tomarCerrojo`). Por
+     * omisión, `linkSync` de verdad. Entra por el mismo motivo que `renombrar`: un test
+     * necesita poder intercalar la recogida COMPLETA de otro proceso en medio de la propia, y
+     * eso no se puede pedir de verdad sin dos procesos reales.
+     */
+    enlazar?: (existente: string, nuevo: string) => void;
+    /**
+     * Cómo se BORRA la cuarentena al final de la recogida. Por omisión, `rmSync` de verdad.
+     * Entra por el mismo motivo que `renombrar` y `enlazar`: es el único punto desde el que se
+     * puede provocar el orden en que la cuarentena COMPARTIDA se llevaba por delante un
+     * cerrojo vivo (ver `tomarCerrojo`), y ese orden no se puede pedir de verdad sin dos
+     * procesos reales.
+     */
+    borrar?: (ruta: string) => void;
+}): TareasEnDisco;
+export interface ResultadoDeFeedback {
+    hecho: boolean;
+    /** Por qué no, si `hecho` es falso. Una frase para enseñar, nunca una excepción cruda. */
+    motivo?: string;
+}
+/**
+ * Añade un feedback a una tarea «esperando feedback» y la devuelve al lazo (`nuevo`).
+ *
+ * §0 del diseño, textual: «se edita la tarea y se agrega el feedback del usuario». Esto es
+ * exactamente eso — y nada más: no toca el proyecto, no abre ninguna consola, solo escribe
+ * el índice. Quien lo recoge es el corredor, en su siguiente `revisar()`.
+ *
+ * Solo toma `listar`/`guardar` del puerto, no la interfaz entera: es lo mínimo que hace
+ * falta, y es lo que ya usa `atenderCrearTarea`/`atenderAccionDeTarea` en `arranque.ts`
+ * (`Pick<TareasEnDisco, "listar" | "guardar" | "borrarTarea">`) — con esto, `aplicarFeedback`
+ * encaja ahí sin ensanchar ese tipo.
+ *
+ * **El rechazo se DEVUELVE, nunca se lanza.** Es la misma regla que `write_file`
+ * (`agent/grafo/proyecto.ts`): quien llama —el cable, o un test— necesita poder decir por qué sin
+ * envolver esto en un `try`, y un `{hecho:false}` es más fácil de propagar hasta una persona
+ * que una excepción.
+ *
+ * **Dos motivos de rechazo, y los dos pasan por `conFeedback`/`conEstado` sin duplicar la
+ * lógica aquí**: un feedback en blanco —devolvería la tarea al lazo sin nada nuevo que
+ * decirle, el mismo argumento que rechaza un título vacío en `sesiones.ts#renombrarSesion`—
+ * y una tarea que no está `requiere-atencion` —no hay pregunta que este feedback esté
+ * contestando—. `conEstado` ya sabe decir la segunda (`«nuevo» no puede pasar a «nuevo»`,
+ * etc.); repetir esa comprobación aquí sería la misma regla en dos sitios que divergen.
+ */
+export declare function aplicarFeedback(disco: Pick<TareasEnDisco, "listar" | "guardar">, id: string, texto: string): ResultadoDeFeedback;
+/**
+ * Cambia el encargo de una tarea que todavía no ha arrancado (IXCODE-52). La regla es la de
+ * `core/tareas.ts#conEncargo`; aquí solo se relee, se aplica y se guarda, y una negativa se
+ * DEVUELVE con su motivo, igual que el feedback.
+ */
+export declare function aplicarEncargo(disco: Pick<TareasEnDisco, "listar" | "guardar">, id: string, encargo: string, 
+/** También la petición, de la que sale el título (IXCODE-53). Ausente = no se toca. */
+peticion?: string, 
+/** La pantalla de Stitch (ya comprobada): nueva, `null` para quitarla, ausente = no se toca. */
+pantalla?: PantallaElegida | null): ResultadoDeFeedback;

package/dist/agent/trazaDeErroresEnDisco.d.ts

@@ -0,0 +1,10 @@
+export declare const VARIABLE_TRAZA_ERRORES = "XONECODE_TRACE_ERRORES";
+export declare const NOMBRE_TRAZA_ERRORES = "traza-errores.jsonl";
+export declare function rutaTrazaDeErrores(raiz: string): string;
+/**
+ * Enciende la traza si la variable está puesta, y devuelve cómo apagarla.
+ *
+ * Devuelve `undefined` cuando NO se enciende, que es el caso normal: así quien la llama puede
+ * decir si está puesta sin volver a mirar el entorno.
+ */
+export declare function encenderTrazaDeErrores(raiz: string, entorno?: NodeJS.ProcessEnv, escribir?: (ruta: string, linea: string) => void): (() => void) | undefined;

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

@@ -0,0 +1 @@
+export declare function entornoConDepuracion(activa: boolean, entorno?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

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

@@ -0,0 +1,124 @@
+import type { TokenTracker } from "../../vendor/tokenTracking.js";
+import type { ParametrosSeguros } from "./resumenDeTool.js";
+import type { OrigenDeTool } from "./puente.js";
+/**
+ * Activa una traza local. Esta variable, por sí sola, sigue siendo la única palanca de este
+ * módulo — nunca se cablea nada aquí. Que valga "1" por OMISIÓN en una sesión normal (mientras
+ * dure esta etapa de pruebas) es una decisión de `Settings.depurar`, resuelta fuera de este
+ * fichero por `agent/turno/depuracion.ts#entornoConDepuracion` antes de que el `entorno` llegue
+ * a `crearDiagnosticoDeTools`.
+ */
+export declare const VARIABLE_TRAZA_TOOLS = "XONECODE_TRACE_TOOLS";
+export declare const NOMBRE_TRAZA_TOOLS = "traza-tools.jsonl";
+/** Cuánto de un encargo se guarda en la traza. Lo demás se cuenta en `chars`, no se guarda. */
+export declare const TOPE_DEL_ENCARGO_EN_TRAZA = 2000;
+export interface UsoDeModelo {
+    input: number;
+    output: number;
+    cache: number;
+    llamadas: number;
+    contexto: number;
+    /**
+     * Cuántos de los `output` fueron RAZONAMIENTO. **Opcional y ausente-no-es-cero**: un proveedor que no lo
+     * declara no piensa cero tokens, simplemente no lo dice, y un cero inventado se leería como «este agente
+     * no razona». Existe porque la salida mezcla razonamiento, texto y llamadas a tools, y sin separarlos no
+     * se puede decidir dónde bajar el esfuerzo.
+     */
+    razonamiento?: number;
+}
+export interface DiagnosticoDeTools {
+    modelo(origen: string, uso: UsoDeModelo): void;
+    /**
+     * Un especialista al que se le agotó el presupuesto de llamadas.
+     *
+     * **OPCIONAL**, como los métodos nuevos de `Piel`: así ningún doble de los tests se rompe por
+     * existir esto, y quien no lo implemente sigue funcionando igual.
+     *
+     * Existe porque un corte era INDISTINGUIBLE de un agente que termina: la traza decía «15
+     * llamadas» en los dos casos. Eso costó una sesión entera de diagnóstico equivocado —se leyó
+     * como un fallo de enrutado lo que era el tope cortando— y es el tipo de dato que solo se
+     * echa de menos cuando ya te ha engañado.
+     */
+    corte?(origen: string, limite: number): void;
+    /**
+     * `origen` distingue el orquestador de un especialista, y es EXACTO (sale del namespace del
+     * stream, ver `puente.ts#esDelPadre`). No dice CUÁL especialista: sus segmentos son ids
+     * opacos. Dos cubos ciertos en vez de cinco dudosos.
+     */
+    herramienta(nombre: string, detalle: string | undefined, parametros: ParametrosSeguros | undefined, tracker: TokenTracker, origen?: OrigenDeTool, respuesta?: string, agente?: string): void;
+    /**
+     * **Quién le pide qué a quién.** Opcional, como `corte`: una delegación del orquestador a un especialista,
+     * con el ENCARGO. Existe porque la traza decía «un especialista» y no cuál, y de lo que el orquestador
+     * pedía solo dejaba una huella: al analizar cuántas pasadas gasta una tarea, la pregunta es qué pidió a
+     * quién y qué hizo cada uno con ello.
+     *
+     * **Es lo único de la traza que lleva TEXTO LIBRE**, y por eso está acotado: recortado a
+     * `TOPE_DEL_ENCARGO_EN_TRAZA` caracteres y solo con la traza encendida. La traza es un fichero local
+     * bajo `.xonecode/` —no viaja por el cable, no entra en git ni sube a CloudStudio—, pero un encargo
+     * puede citar contenido del proyecto, así que quien enciende «Depurar» tiene que saber que queda escrito.
+     */
+    delegacion?(de: string, a: string, encargo: string): void;
+    /**
+     * **Lo que un especialista DEVUELVE a quien lo llamó**, la otra mitad de `delegacion`, con el mismo tope de texto. Existe
+     * porque la traza guardaba el encargo y no la respuesta: en calc15 no se podía saber si el diseñador había dicho qué
+     * fondo era de qué control, ni por qué el orquestador se puso a releer sus SVG. Opcional, como `delegacion`.
+     */
+    devolucion?(de: string, a: string, respuesta: string): void;
+    /**
+     * La memoria de un especialista en la sesión (`memoriaDeEspecialistas.ts`): con cuántos tokens de su
+     * conversación anterior arrancó una encarnación, o por qué arrancó sin memoria, y qué se hizo con la
+     * suya al terminar. Opcional, como `corte`. Es lo que permite comparar una pasada con y sin ella.
+     */
+    memoria?(agente: string, evento: "arranca-con" | "arranca-sin" | "cierra", dato: string, tokens?: number): void;
+    /**
+     * **Cuánto METIÓ en el contexto lo que devolvió una tool.** Opcional, como `corte`.
+     *
+     * Contar llamadas no dice a donde van los tokens: dos `read_file` son dos líneas iguales y
+     * pueden ser doscientos caracteres o veinte mil. Van los CARACTERES y nunca el contenido, y
+     * no se convierten a tokens — la razón cambia con el modelo y con lo que haya dentro, así
+     * que una cifra de tokens aquí sería una precisión inventada.
+     */
+    resultado?(nombre: string | undefined, detalle: string | undefined, chars: number): void;
+    /**
+     * **Las cifras de un turno según NOSOTROS y según el motor**, y en qué difieren. Opcional, como
+     * `corte`: solo TrueForge lleva cuentas propias con las que contrastar
+     * (`motores/trueforge/metricasTrueforge.ts`). Es diagnóstico: una diferencia es una cuenta que
+     * se pierde en un lado, y sin esto no había forma de verla.
+     */
+    /**
+     * **El ENTORNO de la shell de un agente** al montarla (`core/shellDeAgente.ts#resumenDelEntorno`): plataforma, la clave
+     * del PATH, cuántas carpetas, si `node` y `adb` están, cuántos scripts. Opcional, como `corte`. Existe por Windows:
+     * el PATH de los agentes estaba roto («node: command not found») y la traza no decía nada del entorno.
+     */
+    entorno?(agente: string, resumen: Readonly<Record<string, string | number | boolean>>): void;
+    /**
+     * **Lo que hace la shell de un hijo EXTERNO** (Claude Code): cada `Bash` que pide —el comando, el que se ejecutó tras
+     * reescribirlo, y si se permitió o se denegó con su motivo— y lo que salió (tamaño y el comienzo del error). Opcional.
+     * Recortado a `TOPE_DE_TEXTO_EXTERNO`: un comando puede llevar rutas de la máquina, y la traza es un fichero local.
+     */
+    externo?(agente: string, datos: Readonly<Record<string, string | number | boolean | undefined>>): void;
+    contraste?(contraste: {
+        nuestras: {
+            entrada: number;
+            salida: number;
+            cache: number;
+            llamadas: number;
+        };
+        motor: Record<string, number>;
+        externos: number;
+        diferencias: string[];
+    }): void;
+}
+/** Cuánto texto de un comando o de su salida guarda la traza de un hijo externo. */
+export declare const TOPE_DE_TEXTO_EXTERNO = 600;
+/** Ruta pública solo para comunicar al usuario dónde quedó su diagnóstico. */
+export declare function rutaTrazaDeTools(raiz: string): string;
+/**
+ * Crea un registro append-only de costes y calls, con solo argumentos de una
+ * lista blanca; nunca incluye contenido de tools.
+ *
+ * JSONL permite analizar una sesión grande sin tener que cargarla entera. Es
+ * deliberadamente síncrono: son registros minúsculos de un modo de diagnóstico
+ * y así no se pierde la última llamada si el usuario cancela el proceso.
+ */
+export declare function crearDiagnosticoDeTools(raiz: string, entorno?: NodeJS.ProcessEnv, chat?: string | (() => string | undefined)): DiagnosticoDeTools | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * Recorre la raíz y devuelve las rutas en el ESPACIO VIRTUAL del backend.
+ *
+ * Exportada porque la consola la usa para el completado de «@ficheros» (cli puede
+ * importar de agent; al revés no). El recorrido se hace EN CADA llamada a propósito:
+ * la lista no se cachea porque los ficheros cambian durante la sesión.
+ */
+/** Hasta dónde baja el completado del Tab. El árbol de la consola web pide más (`arbolDeProyecto.ts`). */
+export declare const PROFUNDIDAD_DEL_TAB = 4;
+export declare function ficherosDelProyecto(raiz: string, prof?: number, tope?: number): ReadonlySet<string>;

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

@@ -0,0 +1,18 @@
+import { ES_DOBLE } from "../../core/ports.js";
+import type { DomainEvent } from "../../core/events.js";
+/**
+ * Un turno completo de pega, para ver el motor correr sin API ni red.
+ *
+ * Lleva la marca de doble: `xonecode describe` (fase 5) tiene que poder decir que lo que
+ * está montado no es el agente de verdad. Un mock que no se declara hace creer que el
+ * sistema funciona.
+ *
+ * El guion recorre a propósito las cosas que cuestan de pintar: una racha de tools, una
+ * verificación en rojo, una reparación, y una respuesta troceada en varios mensajes.
+ */
+export declare class AgenteGuionizado {
+    private readonly retardoMs;
+    readonly [ES_DOBLE] = true;
+    constructor(retardoMs?: number);
+    turno(peticion: string): AsyncIterable<DomainEvent>;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * El LECTOR de `.xonecode/traza-tools.jsonl`: a dónde se fueron los tokens.
+ *
+ * La traza la escribe `diagnosticoDeTools.ts` y hasta ahora no la leía nadie — un fichero
+ * que solo se escribe es un fichero que no contesta nada. Esto la agrega por ORIGEN (el
+ * orquestador y cada especialista) y por TOOL, que son las dos preguntas con las que se
+ * decide qué recortar: quién gasta, y qué se está leyendo dos veces.
+ *
+ * Es código PURO —recibe líneas, devuelve un resumen— y por eso lleva test: un contador que
+ * cuenta mal invalida en silencio todo lo que se decida mirándolo, igual que un juez de los
+ * evals. Quien toca disco es `cli/traza.ts`.
+ *
+ * **La trampa del formato, y es la razón de la primera prueba**: en una línea `modelo`,
+ * `input`, `output` y `cache` son los de ESA llamada, pero `llamadas` es el acumulado del
+ * tracker en ese instante (1, 2, 3…) y además es GLOBAL, no del origen. Sumarlo daría seis
+ * llamadas donde hubo tres. Las llamadas se cuentan por línea.
+ */
+import type { ConsumoDeSesionPorCuenta } from "../../core/ports.js";
+/** Lo que gastó un origen: el orquestador, o un especialista por su nombre. */
+export interface GastoDeOrigen {
+    origen: string;
+    llamadas: number;
+    input: number;
+    output: number;
+    cache: number;
+    /**
+     * Cuántos tokens de la salida fueron RAZONAMIENTO, sumando SOLO las llamadas que lo declararon
+     * (`conRazonamiento`). **Cero y «no consta» no son lo mismo**: un proveedor que no lo dice no piensa cero
+     * tokens, y por eso se cuenta aparte cuántas llamadas lo traían; el informe solo lo pinta si consta.
+     */
+    razonamiento: number;
+    conRazonamiento: number;
+    /** La salida de ESAS mismas llamadas: el porcentaje se calcula sobre ella y no sobre toda la salida. */
+    salidaConRazonamiento: number;
+    /** La MAYOR ventana alcanzada, no la última: tras un resumen el contexto baja. */
+    contexto: number;
+    /**
+     * Cuántas veces a ESTE origen se le agotó el presupuesto de llamadas.
+     *
+     * Cero y ausente son lo mismo aquí a propósito: un origen que nunca se cortó no tiene nada
+     * que decir. Lo que NO puede pasar es que un corte no aparezca — «15 llamadas» se lee
+     * exactamente igual viniendo de un agente que terminó que de uno al que cortaron, y esa
+     * confusión costó una sesión entera de diagnóstico equivocado.
+     */
+    cortes: number;
+}
+/**
+ * Sobre QUÉ actuó una tool: la ruta o el patrón, y el trozo que pidió.
+ *
+ * **La identidad es ruta + rango, no la ruta.** La instrucción que el agente recibe es «no
+ * releas la misma ruta y el mismo rango» (`DESCRIPCIONES_FICHEROS.read_file`), así que otra
+ * página del mismo fichero es trabajo NUEVO: colapsarla con la primera la disfrazaría de
+ * desperdicio y mandaría a arreglar lo que está bien.
+ */
+export interface BlancoDeTool {
+    detalle: string;
+    /** `offset+limit`, cuando la tool los lleva. Ausente si no los declaró. */
+    rango?: string;
+    veces: number;
+}
+/** Una tool, cuántas veces, y sobre qué. */
+export interface UsoDeTool {
+    nombre: string;
+    veces: number;
+    /** Ordenados por veces: lo repetido primero, que es lo que se viene a buscar. */
+    blancos: BlancoDeTool[];
+    /** Cuántos blancos DISTINTOS: «seis lecturas» y «seis ficheros» no son lo mismo. */
+    distintos: number;
+}
+/**
+ * **Que pidio el modelo EN LA MISMA respuesta**, que es lo unico que decide si dos tools
+ * corren a la vez: langgraph ejecuta las tool_calls de un mensaje concurrentemente.
+ *
+ * Esto existe porque la pregunta se contesto dos veces con dos metodos y dieron dos numeros.
+ * Sobre un turno real de 69 tools, agrupar por el RELOJ exacto daba 18 en rafaga —el
+ * milisegundo parte una rafaga por la mitad— 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.
+ * Hubo que cruzar los dos criterios para defender un numero, y eso es la señal de que
+ * faltaba el dato: ahora cada tool dice de qué mensaje salió.
+ */
+export interface Paralelismo {
+    /** Respuestas que pidieron MAS DE UNA tool. */
+    respuestas: number;
+    /** Tools pedidas dentro de una respuesta multiple. */
+    tools: number;
+    /** El maximo pedido de una vez. */
+    maximo: number;
+    /**
+     * Tools sin `respuesta`: de una traza anterior a este campo. No se cuentan a ningun lado.
+     * Ausente no es `sola`, la misma regla que `toolsDelOrquestador`.
+     */
+    sinRespuesta: number;
+    /**
+     * **El hallazgo que esto vino a buscar**: un fichero escrito mas de una vez en la MISMA
+     * respuesta. Son escrituras concurrentes sobre el mismo contenido, y ahi se pierden
+     * cambios — medido con el backend de verdad, cuatro ediciones simultaneas dejaron UNA.
+     */
+    escriturasALaVez: Array<{
+        detalle: string;
+        veces: number;
+    }>;
+}
+/**
+ * **Cuánto METIÓ en el contexto lo que devolvió una tool, que no es cuántas veces se llamó.**
+ *
+ * Dos `read_file` son dos líneas iguales en el reparto de arriba y pueden ser doscientos
+ * caracteres o veinte mil. Lo que se paga es esto. Salió de buscar por qué un turno costaba
+ * mucho más que el mismo turno de por la mañana: se podía contar cuántas veces se leía el
+ * `SKILL.md` de una skill, pero no lo que pesaba — y por eliminación no se llega.
+ *
+ * **Son CARACTERES y no se convierten a tokens**: la razón cambia con el modelo y con lo que
+ * haya dentro, así que dar tokens aquí sería inventarse una precisión que no se tiene. Para
+ * comparar dos turnos sirve igual.
+ */
+export interface PesoEnContexto {
+    /** La tool, si consta de que llamada era su resultado. */
+    nombre?: string;
+    /** El BLANCO de la lista blanca: la ruta, el patrón, el comando. */
+    detalle?: string;
+    /** Caracteres devueltos, sumados. */
+    chars: number;
+    /** Cuantas veces. `chars` entre `veces` dice si es una gorda o muchas pequeñas. */
+    veces: number;
+}
+export interface SesionDeTraza {
+    id: string;
+    llamadas: number;
+    input: number;
+    output: number;
+    cache: number;
+    contexto: number;
+    origenes: GastoDeOrigen[];
+    tools: UsoDeTool[];
+    /** Qué tools llamó CADA agente, por nombre. Vacío en una traza anterior a que se registrara. */
+    toolsPorAgente: Array<{
+        agente: string;
+        total: number;
+        tools: Array<{
+            nombre: string;
+            veces: number;
+        }>;
+    }>;
+    /** Lo que el orquestador pidió a cada especialista, con el encargo (acotado). */
+    delegaciones: Array<{
+        de: string;
+        a: string;
+        chars: number;
+        encargo?: string;
+    }>;
+    /** Encarnaciones de especialistas que arrancaron con memoria (tokens de su historial) y sin ella. */
+    memoria: {
+        con: number;
+        sin: number;
+        tokens: number;
+    };
+    /**
+     * Cuántas tools gastó el ORQUESTADOR. El resto son de los especialistas.
+     *
+     * Dos cubos y no cinco porque el dato solo da para dos: el namespace del stream dice si un
+     * chunk es del padre o de un especialista, pero no de CUÁL —sus segmentos son ids opacos—.
+     * Repartir entre los cinco pedía una heurística que ya se vio fallar (daba 21 tools a uno
+     * cuyo tope son 20), y un número que parece un dato y es una inferencia es peor que no
+     * tenerlo. El cubo que hacía falta para decidir el presupuesto del orquestador es uno de
+     * estos dos.
+     */
+    toolsDelOrquestador: number;
+    paralelismo: Paralelismo;
+    /** De dónde sale el contexto, lo más gordo primero. Ver `PesoEnContexto`. */
+    pesos: PesoEnContexto[];
+    /** Todo lo que devolvieron las tools, sumado. */
+    charsDeTools: number;
+    /** Líneas que no se pudieron leer. Se dicen: una traza a medias no se disimula. */
+    ilegibles: number;
+    /**
+     * El contraste de NUESTRAS cifras con las del motor, turno a turno (solo TrueForge lleva cuentas
+     * propias: `motores/trueforge/metricasTrueforge.ts`). Ausente = esta sesión no se contrastó, que
+     * no es lo mismo que «coinciden».
+     */
+    contraste?: {
+        turnos: number;
+        conDiferencias: number;
+        diferencias: string[];
+    };
+}
+/**
+ * Tokens EQUIVALENTES para comparar dos ejecuciones del mismo modelo, no una factura.
+ *
+ * Asume la caché a un décimo, que es el orden de magnitud que declaran los proveedores que
+ * la cobran. La misma cuenta que imprime el corredor de evals, y vive aquí para que sea UNA:
+ * dos fórmulas para el mismo número son dos números que acaban divergiendo.
+ */
+export declare function costeEfectivo(uso: {
+    input: number;
+    output: number;
+    cache: number;
+}): number;
+/**
+ * Agrupa las líneas por sesión, en el orden en que aparece cada una.
+ *
+ * El fichero es append-only y una máquina acumula varias ejecuciones: sin partir por
+ * `sesion` el informe sumaría el turno de ayer al de ahora y nadie lo notaría, porque la
+ * cifra resultante es perfectamente plausible.
+ */
+export declare function resumirTraza(lineas: Iterable<string>): SesionDeTraza[];
+export declare function pintarSesion(sesion: SesionDeTraza): string[];
+/**
+ * Lo que costó UN turno, para cerrarlo con una cifra en vez de con un silencio.
+ *
+ * **Las dos cuentas no se suman**, y por eso son dos filas: los tokens del grafo van contra
+ * la clave de API de quien corre y los del agente EXTERNO contra su suscripción. Un token es
+ * un token, pero su precio no, así que un total sería una cifra que no significa nada.
+ *
+ * La cuenta externa **ausente se calla**: una fila de ceros afirma que se midió un agente
+ * externo que no corrió. Y una `ventana` de cero es «no se pudo medir», no «cabe todo»:
+ * misma regla que `consumoPersistible`, que tampoco la estampa.
+ *
+ * Vive aquí y no en `cli/run.ts` por el patrón de fallo de este repo: compuesta dentro de
+ * `correrReal` —que todos sus tests doblan— la regla quedaría escrita y sin nadie mirándola.
+ */
+export declare function pintarGasto(consumo: ConsumoDeSesionPorCuenta, llamadas: number): string[];