xonecode 0.38.44 → 0.39.2

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

@@ -0,0 +1,35 @@
+/**
+ * TODO lo que XOneCode usa de `@truefoundry/trueforge-core`, por un solo sitio.
+ *
+ * La librería es 0.x (fijada EXACTA a 0.2.1 en `package.json`) y no promete compatibilidad entre
+ * versiones. Con los imports repartidos por el motor, subirla obligaba a revisar cada fichero; aquí
+ * se revisa uno. Dos clases de cosas, y se separan a propósito:
+ *
+ * - Lo de la API PÚBLICA (`@truefoundry/trueforge-core/core`): el orquestador, los hilos, las
+ *   capabilities, `ILLM`.
+ * - Lo que SOLO está en rutas profundas: los tipos de los fragmentos del modelo y el trazado mudo.
+ *   El paquete los deja importar (`"./*"` en sus `exports`), pero no son su API: son lo primero
+ *   que puede moverse en una versión nueva, y por eso viven aquí y en ningún otro sitio.
+ *
+ * El trazado mudo (`NOOP_AGENT_TRACING`) es NUESTRO y va con `satisfies` contra los tipos PÚBLICOS
+ * de la librería: si su interfaz cambia, el compilador lo dice aquí. Era una ruta profunda más, y la
+ * única que no era un tipo.
+ */
+/**
+ * La versión de la librería con la que corre este motor, la MISMA que fija `package.json`
+ * (`frontera.test.ts` compara las dos, y contra la instalada). Viaja en la foto de memoria
+ * (`memoriaTrueforge.ts`) para que una migración futura sepa con qué `toSnapshot()` se escribió.
+ * Es una constante y no una lectura de su `package.json`: leerlo desde otro fichero sería una
+ * segunda puerta a la librería, y aquí subirla se revisa de todas formas.
+ */
+export declare const VERSION_DE_TRUEFORGE = "0.2.1";
+export { AgentThread, AgentThreadOrchestrator, EventType, ToolSet, askUserQuestion, contextCompaction, currentDateTime, dynamicSubAgents, openUI, toolResultResponse, } from "@truefoundry/trueforge-core/core";
+export type { AgentTracing, ILLM, LLMCreateParams, LLMCreateParamsStreaming } from "@truefoundry/trueforge-core/core";
+import type { AgentExecutionTrace, AgentLocalToolTrace, AgentRemoteMcpToolTrace } from "@truefoundry/trueforge-core/core";
+export type { ExtendedChatCompletionChunk, RawAssistantMessageWithUsage } from "@truefoundry/trueforge-core/core/llm/LLMTypes";
+export declare const NOOP_AGENT_TRACING: {
+    withInitSpan: <T>(operation: () => Promise<T>) => Promise<T>;
+    startRootSpan: () => AgentExecutionTrace;
+    withLocalToolSpan: <T>(_input: unknown, operation: (span: AgentLocalToolTrace) => Promise<T>) => Promise<T>;
+    withRemoteMcpToolSpan: <T>(_input: unknown, operation: (span: AgentRemoteMcpToolTrace) => Promise<T>) => Promise<T>;
+};

package/dist/agent/navegacion/estilosEnDisco.d.ts

@@ -0,0 +1,41 @@
+import { type EstiloDeProp } from "../../core/estilos.js";
+/** Lo poquito del modelo del linter que hace falta aquí. Declarado en vez de importado por la
+ *  misma razón que `ModeloDelLinter`: no arrastrar sus tipos por medio harness. */
+interface ModeloConEstilos {
+    app: {
+        attributes: Record<string, string>;
+        styles: Array<{
+            url: string;
+        }>;
+    };
+    colls: Array<{
+        name: string;
+        attributes?: Record<string, string>;
+        props?: Array<{
+            name: string;
+            type?: string;
+            attributes?: Record<string, string>;
+        }>;
+        groups?: Array<{
+            props?: Array<{
+                name: string;
+                type?: string;
+                attributes?: Record<string, string>;
+            }>;
+        }>;
+    }>;
+    cssFiles: Map<string, string>;
+}
+export type CargarEstilos = (coleccion: string, prop: string) => Promise<EstiloDeProp | undefined>;
+/**
+ * El resolvedor de estilos de un proyecto, leyendo el disco con `xone-linter`.
+ *
+ * **No cachea**, por lo mismo que el índice de navegación: el agente escribe CSS dentro del
+ * turno, y una hoja vieja que afirma que una clase pone 14 cuando acaba de ponerse 18 es peor
+ * que no tener resolvedor — es una respuesta con autoridad y equivocada.
+ *
+ * Devuelve `undefined` cuando la colección o el prop no existen: eso NO es un fallo, es un dato,
+ * y quien llama dice cómo seguir.
+ */
+export declare function estilosEnDisco(cargarModelo: () => Promise<ModeloConEstilos>): CargarEstilos;
+export {};

package/dist/agent/navegacion/hechosEnDisco.d.ts

@@ -0,0 +1,19 @@
+import { type HechosDelProyecto } from "../../core/hechosDelProyecto.js";
+import type { CargarIndice } from "./indiceEnDisco.js";
+/**
+ * Los hechos del proyecto, leyendo el disco, **y tolerando que no se puedan leer**.
+ *
+ * Vive aquí y no dentro del turno por el patrón de fallo que este repo lleva contado nueve
+ * veces: una composición de producción escondida en un cierre que todos los tests doblan es una
+ * regla escrita, no probada. Aquí la costura está fuera y tiene su test.
+ *
+ * **Un fallo NO tumba el turno, y eso es la decisión.** Construir el índice toca disco y entra
+ * en la librería del linter: una carpeta que no es un proyecto XOne, un `.xne` ilegible o un
+ * fallo de la librería devuelven `undefined`, y entonces el turno sale exactamente como salía
+ * antes de que esto existiera. Adelantar hechos es una OPTIMIZACIÓN —abarata enterarse—, no una
+ * capacidad, así que no puede ser lo que impida trabajar. Es el mismo trato que el verificador
+ * le da a que falte el binario: se sigue, y lo que falta se nota en el precio, no en un error.
+ *
+ * Se llama POR TURNO y no al abrir la sesión, a propósito: ver `core/hechosDelProyecto.ts`.
+ */
+export declare function hechosDelProyectoDe(cargarIndice: CargarIndice, ficheros: ReadonlySet<string>): Promise<HechosDelProyecto | undefined>;

package/dist/agent/navegacion/indiceEnDisco.d.ts

@@ -0,0 +1,50 @@
+import { type IndiceDeNavegacion, type ModeloDeNavegacion } from "../../core/navegacion.js";
+import { type CargarEstilos } from "./estilosEnDisco.js";
+/**
+ * El índice de navegación de un proyecto de verdad, leyendo el disco con `xone-linter`.
+ *
+ * **Se apoya en la librería y no reescribe su semántica**, y eso es una decisión medida: el
+ * linter ya parsea `.xne`, ya DECODIFICA la codificación del fichero (los `.xne` en
+ * ISO-8859-15 son reales, y su `XmlParser` lee la declaración en latin1 antes de pasar por
+ * `iconv` para no romper bytes) y su `CrossReferenceRule` ya define qué significa `mapcol`,
+ * `mapfld`, `linkedfield`, `contents src` e `inherits`. Reescribir eso aquí sería un SEGUNDO
+ * sitio donde se decide lo mismo, y el día que divergieran el linter diría una cosa y el
+ * agente otra sobre el mismo proyecto.
+ *
+ * Entra como LIBRERÍA y no como el binario `xone-simulator` que usa el verificador: así
+ * `npm test` puede probar esto con un proyecto de mentira en un temporal, sin binario
+ * instalado, que es el invariante que sostiene todo el diseño de puertos. El precio es que
+ * hay dos copias del linter en juego —la fijada en `node_modules` y la que el usuario tenga
+ * en el PATH— y conviene que no se separen de major.
+ *
+ * **No cachea, a propósito.** Medido sobre un proyecto real de 41 colecciones: cargarlo entero
+ * cuesta unas decenas de milisegundos, contra los segundos de una llamada al modelo. Rehacerlo
+ * en cada consulta sale gratis y quita de en medio la pregunta de cuándo invalidarlo — un
+ * índice viejo que dice que un campo existe cuando el agente acaba de borrarlo es peor que no
+ * tener índice: es una respuesta con autoridad y equivocada.
+ */
+export type CargarIndice = (ficheros: ReadonlySet<string>) => Promise<IndiceDeNavegacion>;
+/**
+ * Devuelve el cargador del índice de una raíz. La raíz se fija al crearlo y NO entra por
+ * parámetro en cada consulta: si el modelo pudiera decir sobre qué proyecto preguntar,
+ * tendríamos una tool que lee cualquier carpeta de la máquina.
+ */
+export declare function indiceEnDisco(raiz: string): CargarIndice;
+/**
+ * El MODELO de navegación de una raíz, ya traducido y filtrado: lo que el índice consulta y lo
+ * que la pestaña Colecciones fotografía (`core/fotoDeColecciones.ts`). Un solo cargador para
+ * los dos, así que lo que ve la persona y lo que ve el agente salen de la misma lectura.
+ */
+export declare function modeloEnDisco(raiz: string): (ficheros: ReadonlySet<string>) => Promise<ModeloDeNavegacion>;
+/**
+ * El resolvedor de ESTILOS de una raíz, sobre el mismo `XoneProject`.
+ *
+ * Vive aquí y no en `estilosEnDisco.ts` para que el import profundo de `XoneProject` —con su
+ * motivo medido escrito arriba— esté en UN solo sitio. `estilosEnDisco` recibe el modelo ya
+ * cargado y no sabe de dónde sale, que es lo que lo deja probable sin proyecto en disco.
+ *
+ * **No cachea**, por lo mismo que el índice: el agente escribe CSS dentro del turno, y una hoja
+ * vieja que afirma que una clase pone 14 cuando acaba de ponerse 18 es una respuesta con
+ * autoridad y equivocada.
+ */
+export declare function estilosDeDisco(raiz: string): CargarEstilos;

package/dist/agent/navegacion/modeloDeProyecto.d.ts

@@ -0,0 +1,86 @@
+import type { ModeloDeNavegacion } from "../../core/navegacion.js";
+/**
+ * De lo que `xone-linter` sabe del proyecto a lo que el índice necesita.
+ *
+ * **Por qué se traduce en vez de usar su modelo tal cual.** Dos razones, y la segunda es la
+ * que importa. La primera: su `XoneProjectModel` trae el proyecto entero —conexiones,
+ * estilos, imágenes, fuentes, el runtime— y atar `core/navegacion.ts` a esa forma haría que
+ * un cambio suyo llegara hasta el núcleo puro. La segunda: **sus rutas son ABSOLUTAS de esta
+ * máquina** (`/Users/…/AppDemo/Clientes.xne`), y de aquí sale texto que va al modelo y de ahí
+ * al cable. Traducir a ruta virtual no es higiene: es la misma regla que `sinRutas`.
+ *
+ * **Y las guardas se REAPLICAN aquí.** Una tool de LangChain que añade xonecode NO pasa por
+ * el middleware de permisos —la lección que ya pagó `busquedaRegex`—, así que lo que este
+ * adaptador devuelve pasa por `puedeLeerRuta` y por `esVistaAplanada` antes de existir. Se
+ * filtra en la FUENTE y no al pintar: lo que no se puede enseñar, mejor que no llegue a estar
+ * en el índice.
+ *
+ * Lo que este módulo NO hace es leer disco por su cuenta ni aceptar rutas del modelo: recibe
+ * el modelo ya cargado y la raíz, y de ahí no se mueve.
+ */
+/** La forma de `xone-linter` que se usa, declarada aquí y mínima. Su `XoneProjectModel` trae
+ *  mucho más; nombrar solo esto es lo que deja ver de un vistazo de qué dependemos. */
+export interface ModeloDelLinter {
+    colls?: readonly CollDelLinter[];
+    /** Ruta RELATIVA del `.js` -> su contenido. Lo carga el linter. */
+    jsFiles?: ReadonlyMap<string, string>;
+    app?: {
+        entryPoints?: readonly string[];
+        loginColls?: readonly string[];
+        styles?: readonly {
+            url?: string;
+        }[];
+        connections?: readonly {
+            name?: string;
+        }[];
+    };
+}
+interface CollDelLinter {
+    name?: string;
+    attributes?: Record<string, string>;
+    location?: {
+        file?: string;
+    };
+    props?: readonly {
+        name?: string;
+        type?: string;
+        attributes?: Record<string, string>;
+        inlineEvents?: readonly {
+            name?: string;
+            script?: string;
+        }[];
+    }[];
+    contents?: readonly {
+        src?: string;
+    }[];
+    events?: readonly EventoDelLinter[];
+    nodes?: readonly EventoDelLinter[];
+    connections?: readonly {
+        name?: string;
+    }[];
+}
+interface EventoDelLinter {
+    name?: string;
+    triggerProp?: string;
+    actions?: readonly {
+        script?: string;
+        value?: string;
+    }[];
+}
+/**
+ * La ruta VIRTUAL de una absoluta del proyecto, o `undefined` si se sale de él.
+ *
+ * Lexical y no `realpath`: este módulo es la traducción, no la barrera del disco — quien
+ * necesite cerrar los enlaces simbólicos lo hace donde se abre el fichero. Aquí lo que se
+ * impide es que una ruta de FUERA se presente como si fuera del proyecto.
+ */
+export declare function rutaVirtualDelProyecto(raiz: string, absoluta: string): string | undefined;
+/**
+ * Traduce el modelo del linter al nuestro, filtrando lo que no se puede enseñar.
+ *
+ * `ficheros` son las rutas virtuales del proyecto, las mismas que ve el agente: hacen falta
+ * para reconocer una vista aplanada (`X.xml` con un `X.xne` al lado), que es una regla que
+ * depende del conjunto y no de la ruta sola.
+ */
+export declare function modeloDeNavegacion(delLinter: ModeloDelLinter, raiz: string, ficheros: ReadonlySet<string>): ModeloDeNavegacion;
+export {};

package/dist/agent/planesEnDisco.d.ts

@@ -0,0 +1,18 @@
+import { type TareasDelPlan } from "../core/tareasDelPlan.js";
+/** Cuánto se lee de un fichero de plan. Uno real ronda los 10-15 KB. */
+export declare const TOPE_DE_FICHERO_DE_PLAN: number;
+export interface PlanEnDisco {
+    nombre: string;
+    /** Cuáles de `PLAN.md`, `TASKS.md` y `CONTEXT.md` tiene: un plan puede ir a medias. */
+    ficheros: string[];
+    /** Las tareas de su `TASKS.md`, si lo tiene. */
+    tareas?: TareasDelPlan;
+    /** El texto de su `PLAN.md`, si lo tiene, acotado. */
+    plan?: {
+        texto: string;
+        recortado: boolean;
+    };
+    /** Cuándo se tocó por última vez algo suyo, en milisegundos: para ordenar, lo reciente arriba. */
+    modificado: number;
+}
+export declare function planesDelProyecto(raiz: string): PlanEnDisco[];

package/dist/agent/publicarPlan.d.ts

@@ -0,0 +1,20 @@
+export interface PlanPublicado {
+    /** Relativa a la raíz, que es como se enseña y como entra en git. */
+    ruta: string;
+    /** Qué se copió, por nombre relativo a la carpeta del plan. */
+    ficheros: string[];
+}
+/**
+ * Copia `<raiz>/.xonecode/planes/<nombre>` a `<raiz>/doc/planes/<nombre>`.
+ *
+ * Devuelve `{error}` en vez de lanzar, como las guardas del backend: el llamador es un
+ * comando de consola y lo que tiene que hacer con un no es decirlo, no reventar.
+ */
+export declare function publicarPlan(opciones: {
+    raiz: string;
+    nombre: string;
+}): PlanPublicado | {
+    error: string;
+};
+/** Los planes que hay en el proyecto, por nombre. Vacío si nadie ha planificado. */
+export declare function planesDelProyecto(raiz: string): string[];

package/dist/agent/raizDelPaquete.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sube desde `desde` hasta la primera carpeta con un `package.json`, o `undefined`.
+ *
+ * Separada de `raizDelPaquete` para poder probar las dos ramas: sin esto, el caso «no hay
+ * ninguna» solo se podría provocar moviendo el repo.
+ */
+export declare function buscarRaizDelPaquete(desde: string): string | undefined;
+/** La raíz del paquete. Lanza si no la hay: ver la cabecera. */
+export declare function raizDelPaquete(desde?: string): string;

package/dist/agent/remoto/ngrokEnMaquina.d.ts

@@ -0,0 +1,44 @@
+/** Lo que se usa del SDK. `forward` abre el túnel; el resto de su API no hace falta. */
+export interface SdkDeNgrok {
+    forward(config: {
+        addr: string;
+        authtoken?: string;
+        domain?: string;
+        onStatusChange?: (estado: string) => void;
+    }): Promise<{
+        url(): string | null;
+        close(): Promise<void>;
+    }>;
+}
+/** El SDK de verdad, o `undefined` si su binario nativo no carga en esta plataforma. Por `import()`: solo se carga al usarlo. */
+export declare function cargarSdkReal(): Promise<SdkDeNgrok | undefined>;
+/** Donde Ajustes guarda el authtoken: un fichero NUESTRO, 0600, nunca el proyecto. */
+export declare const rutaDeAuthtoken: (casa: string) => string;
+export interface DependenciasDeNgrok {
+    cargarSdk?: () => Promise<SdkDeNgrok | undefined>;
+    entorno?: Record<string, string | undefined>;
+    casa?: string;
+    plataforma?: string;
+    /** Lee un fichero de texto; lanza si no se puede. */
+    leer?: (ruta: string) => string;
+    /** Escribe el fichero del authtoken. */
+    escribir?: (ruta: string, contenido: string) => void;
+}
+/** El authtoken que se usará, por el orden de la cabecera, o `undefined` si no hay ninguno. */
+export declare function authtokenDeNgrok(deps?: DependenciasDeNgrok): string | undefined;
+export interface MedidaDeNgrok {
+    instalado: boolean;
+    cuenta: boolean;
+}
+export declare function medirNgrok(deps?: DependenciasDeNgrok): Promise<MedidaDeNgrok>;
+export type ResultadoDeGuardarAuthtoken = {
+    ok: true;
+} | {
+    ok: false;
+    motivo: string;
+};
+/**
+ * Guarda el authtoken en `~/.xonecode/ngrok.json` (0600). Ya no pasa por `ngrok config add-authtoken`, así que el token no
+ * aparece en la línea de órdenes de ningún proceso. Un fallo devuelve un texto FIJO.
+ */
+export declare function guardarAuthtoken(token: string, deps?: DependenciasDeNgrok): Promise<ResultadoDeGuardarAuthtoken>;

package/dist/agent/remoto/puenteWebSocket.d.ts

@@ -0,0 +1,59 @@
+/**
+ * El puente REAL de la sesión remota. Es el ÚNICO fichero que nombra `@xone/xonecode-remoto`,
+ * y lo carga con `import()` dinámico de un nombre en variable: el paquete viaja DENTRO de xonecode
+ * (`vendor/xonecode-remoto/` + `bundleDependencies`), pero se carga perezoso, así que con la sesión
+ * apagada no se toca, y `npm test` no lo necesita (usa `PuenteRemotoEnMemoria`).
+ */
+import type { PuenteRemotoPort } from "../../core/ports.js";
+export declare const NOMBRE_DEL_PAQUETE = "@xone/xonecode-remoto";
+/** La parte del paquete que se usa aquí (su API real tiene más). */
+export interface ModuloRemoto {
+    VERSION_DEL_PROTOCOLO: number;
+    generarCredenciales(): {
+        sala: string;
+        secreto: string;
+    };
+    urlDeSesion(baseHttp: string, sala: string, secreto: string): string;
+    baseHttpDe(servidorWs: string): string;
+    crearCanal(o: {
+        secreto: string;
+        sala: string;
+        rol: "anfitrion";
+    }): Promise<{
+        cifrar(m: unknown): Promise<string>;
+        descifrar(carga: string): Promise<unknown>;
+    }>;
+}
+/** `undefined` = el paquete no está instalado: quien llama lo dice, aquí no se propaga el error. */
+export declare function cargarModuloRemoto(importar?: (nombre: string) => Promise<unknown>): Promise<ModuloRemoto | undefined>;
+/**
+ * La subruta del paquete con el PUENTE (el relé que `xonecode-server` corre en la nube), para la
+ * vía «túnel local»: xonecode lo arranca en loopback y ngrok lo publica (`tunelNgrok.ts`). Vive
+ * aquí para que el nombre del paquete siga en UN fichero.
+ */
+export declare const NOMBRE_DEL_SERVIDOR = "@xone/xonecode-remoto/servidor";
+/** La parte de `@xone/xonecode-remoto/servidor` que se usa. */
+export interface ModuloServidorRemoto {
+    arrancarServidor(o: {
+        puerto: number;
+        host?: string;
+    }): Promise<{
+        urlHttp: string;
+        urlWs: string;
+        cerrar(): Promise<void>;
+    }>;
+}
+/**
+ * `undefined` = el paquete no está, o es una versión sin el puente (sin la subruta, o sin
+ * `arrancarServidor`): quien llama lo dice con su texto fijo.
+ */
+export declare function cargarServidorRemoto(importar?: (nombre: string) => Promise<unknown>): Promise<ModuloServidorRemoto | undefined>;
+/**
+ * Lo que `cerrar` espera, como mucho, a que el relé cierre el socket tras el «cerrar». Sin tope,
+ * un relé que no contesta colgaría el apagado; con él, lo peor es el comportamiento de antes.
+ */
+export declare const TOPE_DE_CIERRE_MS = 2000;
+export declare function crearPuenteWebSocket(modulo: ModuloRemoto, opciones?: {
+    esperasMs?: readonly number[];
+    topeDeCierreMs?: number;
+}): PuenteRemotoPort;

package/dist/agent/remoto/tunelNgrok.d.ts

@@ -0,0 +1,31 @@
+/**
+ * El túnel REAL de la vía «ngrok» de la sesión remota: arranca el puente del paquete en un puerto libre de loopback y abre
+ * el túnel con el SDK de ngrok (`@ngrok/ngrok`, que viene con xonecode) hacia él. Entra en el servidor por opción (un
+ * `TunelPort`), como el puente: ni `core/` ni `web/` importan este fichero.
+ *
+ * Reglas, todas por lo mismo —nada de la máquina cruza el cable—:
+ * - **Un fallo es un texto de `MOTIVOS_DEL_TUNEL`**, clasificado por el CÓDIGO `ERR_NGROK_xxx` que el SDK pone en el error
+ *   (`errorCode`). El mensaje del error se queda aquí: puede llevar el correo de la cuenta o el token.
+ * - **El túnel vive dentro de este proceso**: no hay programa `ngrok` que lanzar, ni log que leer, ni grupo que matar, y
+ *   muere con el proceso —se acabó el ngrok huérfano tras un cierre en seco que había con el programa—.
+ * - **Una pérdida de conexión no es una caída todavía**: el SDK reconecta solo (`onStatusChange`: `closed` y luego
+ *   `connected`). Solo si no ha vuelto en `ESPERA_DE_RECONEXION_MS` se da el túnel por caído y se avisa.
+ * - **Cerrar: el túnel PRIMERO y luego el puente**, para que el móvil no vea un puente vivo detrás de un túnel ya muerto ni
+ *   al revés un túnel que apunta a nada.
+ */
+import type { TunelPort } from "../../core/ports.js";
+import { type SdkDeNgrok } from "./ngrokEnMaquina.js";
+import { type ModuloServidorRemoto } from "./puenteWebSocket.js";
+/** Lo que se espera a que ngrok dé la dirección pública. */
+export declare const TOPE_DE_TUNEL_MS = 30000;
+/** Lo que se espera a que el SDK reconecte tras perder la conexión, antes de dar el túnel por caído. */
+export declare const ESPERA_DE_RECONEXION_MS = 30000;
+export interface DependenciasDelTunel {
+    cargarServidor?: () => Promise<ModuloServidorRemoto | undefined>;
+    cargarSdk?: () => Promise<SdkDeNgrok | undefined>;
+    /** El authtoken que se usará, o `undefined` si no hay cuenta. */
+    authtoken?: () => string | undefined;
+    topeMs?: number;
+    esperaDeReconexionMs?: number;
+}
+export declare function crearTunelNgrok(deps?: DependenciasDelTunel): TunelPort;

package/dist/agent/renombrarSobre.d.ts

@@ -0,0 +1,14 @@
+/** Esperas entre intentos, en milisegundos: crecen y suman algo más de un segundo. */
+export declare const ESPERAS_DE_RENOMBRADO_MS: readonly number[];
+export interface OpcionesDeRenombrado {
+    /** Inyectable para los tests; por omisión `process.platform`. */
+    plataforma?: NodeJS.Platform;
+    /** Cómo esperar entre intentos (síncrona en `renombrarSobreSync`). */
+    dormir?: (ms: number) => void | Promise<void>;
+    /** El rename de verdad; inyectable para simular el bloqueo. */
+    rename?: (origen: string, destino: string) => void | Promise<void>;
+}
+/** `renameSync` que, en Windows, aguanta el bloqueo pasajero de un antivirus o un indexador. */
+export declare function renombrarSobreSync(origen: string, destino: string, opciones?: OpcionesDeRenombrado): void;
+/** La versión asíncrona, para quien ya escribe con `node:fs/promises`. */
+export declare function renombrarSobre(origen: string, destino: string, opciones?: OpcionesDeRenombrado): Promise<void>;

package/dist/agent/sesiones/adjuntosDeSesion.d.ts

@@ -0,0 +1,64 @@
+import { type AdjuntoNombrable } from "../../core/adjuntos.js";
+/** Bytes que se aceptan por adjunto y por sesión. Mismos valores que `TOPE_DE_ADJUNTO` /
+ *  `TOPE_DE_ADJUNTOS_POR_TAREA` de `tareasEnDisco.ts`: es la misma regla, aplicada a otra cola. */
+export declare const TOPE_DE_ADJUNTO_DE_SESION = 20000000;
+export declare const TOPE_DE_ADJUNTOS_POR_SESION = 50000000;
+/** Los topes de `guardarAdjuntoDeSesion`, inyectables para probarlos sin escribir megabytes. */
+export interface TopesDeAdjuntosDeSesion {
+    porFichero: number;
+    porSesion: number;
+}
+/**
+ * Guarda un adjunto anexado en el chat de la sesión `id`, dentro del proyecto `raiz`.
+ *
+ * Mismo orden que `tareasEnDisco.ts#guardarAdjunto`: primero lo que se sabe SIN tocar disco (el
+ * nombre, el tamaño del propio fichero), luego la carpeta —comprobada, no creada— y solo con
+ * ella en la mano el tope por sesión (que necesita leer lo que ya hay) y la escritura.
+ *
+ * **NUNCA sobrescribe** (Ronda de arreglo 1/5, IXCODE-7): la carpeta es por SESIÓN y sobrevive
+ * a que el compositor vacíe sus fichas al enviar, así que dos turnos que suban el mismo nombre
+ * —un `pegado-1.png` es el caso típico— pisarían en silencio el fichero del turno anterior sin
+ * este paso. `nombreLibreEn` decide el nombre FINAL, que puede llevar sufijo; se devuelve en
+ * `{ok:true, nombre}` para que quien llama (la ruta HTTP, y con ella la ficha del compositor)
+ * sepa con qué nombre quedó de verdad.
+ *
+ * **Las cuatro llamadas de disco van en un `try`**: `mkdirSync` (un `EACCES` de permisos),
+ * `readdirSync`/`statSync` al sumar lo que ya hay (un `ENOSPC`, o un enlace COLGANTE dentro de
+ * `adjuntos/` — `statSync` lo sigue y `ENOENT` si el destino no existe) y `writeFileSync`. Un
+ * rechazo de guarda se DEVUELVE, nunca se lanza: sin este `try`, cualquiera de esos errores se
+ * llevaba por delante al llamador (`POST /adjunto`), que no los esperaba.
+ */
+export declare function guardarAdjuntoDeSesion(raiz: string, id: string, nombre: string, datos: Buffer, topes?: TopesDeAdjuntosDeSesion): {
+    ok: true;
+    nombre: string;
+    extraidos?: string[];
+    sinExtraer?: string;
+} | {
+    ok: false;
+    motivo: string;
+};
+/**
+ * Lo que hay en la carpeta de adjuntos de la sesión `id`, medido del DISCO.
+ *
+ * Ordenado por nombre, y solo ficheros LLANOS con nombre aceptable: una carpeta o un enlace ahí
+ * no es un adjunto, y `readdirSync` los daría igual. Con `nombres`, filtra a esa lista — en su
+ * mismo ORDEN, omitiendo los que no estén — para poder pedir «los adjuntos DE ESTE MENSAJE» sin
+ * enseñar los de mensajes anteriores de la misma sesión.
+ */
+export declare function listarAdjuntosDeSesion(raiz: string, id: string, nombres?: readonly string[]): AdjuntoNombrable[];
+/**
+ * Copia unos adjuntos de la sesión `id` a otra carpeta —la de una TAREA—, con el árbol extraído de
+ * cada `.zip` si lo hay. Lo usa encolar una propuesta de tareas encadenadas: cada tarea se lleva SUS
+ * diseños y nada más, y se copian ANTES de guardar la tarea, porque el corredor puede arrancarla en
+ * el acto.
+ *
+ * Las guardas son las de leer: la carpeta de la sesión por `carpetaComprobada`, cada nombre por
+ * `nombreDeAdjuntoAceptable`, y solo ficheros y carpetas de verdad —un enlace no se sigue ni se
+ * copia—. El destino lo da quien llama, ya comprobado (`TareasEnDisco.carpetaDeAdjuntos`).
+ * Devuelve qué se copió y qué no estaba: un nombre que el agente escribió mal no tumba el encolado,
+ * se DICE.
+ */
+export declare function copiarAdjuntosDeSesion(raiz: string, id: string, nombres: readonly string[], destino: string): {
+    copiados: string[];
+    faltan: string[];
+};

package/dist/agent/sesiones/baseDeFichero.d.ts

@@ -0,0 +1,9 @@
+export type BaseDeComparacion = "sesion" | "commit";
+export interface BaseLeida {
+    ruta: string;
+    base: BaseDeComparacion;
+    texto?: string;
+    vacio?: true;
+    sinBase?: string;
+}
+export declare function baseDeFichero(raiz: string, sesion: string | undefined, ruta: string, base: BaseDeComparacion): Promise<BaseLeida>;