xonecode 0.38.44 → 0.39.4

package/dist/agent/config/configEnDisco.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Leer los dos ficheros de configuración del disco y volcar las credenciales en el
+ * entorno. Aquí está el I/O que `core/config.ts` no quiere: rutas, `readFileSync` y
+ * `statSync`; lo que llega a `validar`/`validarAuth` es solo datos.
+ */
+import { closeSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { Aviso, Auth, ConfigDeFichero, Procedencia } from "../../core/config.js";
+import type { DisenoVinculado } from "../../core/stitch.js";
+import type { VinculoGuardado } from "../../core/gestorDeTareas.js";
+import { Proveedor, type ProveedorDeclarado } from "../../core/modelos.js";
+import type { Papel } from "../../core/ports.js";
+import type { ModoDeEscritura } from "../../core/modoDeEscritura.js";
+export declare const NOMBRE_CARPETA = ".xonecode";
+export declare class ConfigRotaEnDisco extends Error {
+    constructor(ruta: string, causa?: unknown);
+}
+export declare function rutaConfigGlobal(): string;
+export declare function rutaConfigDeProyecto(raiz: string): string;
+export declare function rutaAuth(): string;
+export interface OperacionesDeEscritura {
+    openSync: typeof openSync;
+    writeFileSync: typeof writeFileSync;
+    closeSync: typeof closeSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
+}
+/** Guarda una elección de papel sin perder el resto del config global. */
+export declare function guardarModeloGlobal(papel: Papel, id: string, operaciones?: OperacionesDeEscritura): {
+    ruta: string;
+    id: string;
+};
+/**
+ * Los proveedores personalizados dados de alta, del config GLOBAL y de ningún otro.
+ *
+ * No recibe raíz a propósito: el registro no depende del proyecto, y darle una invitaría a
+ * pensar que el `config.json` del proyecto también cuenta — que es justo lo que
+ * `core/config.ts` rechaza, porque la clave se guarda por identificador y un proyecto que
+ * redefiniera la URL de un slug ya dado de alta la mandaría a otro host.
+ *
+ * Lee de disco en cada llamada, sin caché: la ventana de ajustes da de alta en caliente, y
+ * una lista capturada al arrancar se quedaría vieja hasta reiniciar. Un fichero ilegible
+ * devuelve la lista vacía; quien tiene que contar ESE problema es `cargar`, que ya lo hace
+ * con sus avisos y es quien se pinta.
+ */
+export declare function proveedoresPersonalizados(): readonly ProveedorDeclarado[];
+/**
+ * Da de alta —o vuelve a escribir— un proveedor personalizado en el config GLOBAL.
+ *
+ * Tres cosas, y las tres tienen su porqué:
+ * - **Global y solo global.** La razón está en `core/config.ts` («proveedores»): la clave
+ *   se guarda por identificador, así que un proyecto que pudiera redefinir la URL de un
+ *   slug ya dado de alta mandaría esa clave a otro host. Aquí ni se ofrece la opción.
+ * - **Vuelve a pasar por el VALIDADOR** antes de escribir. Este fichero se edita también a
+ *   mano, así que la autoridad sobre si un alta vale es el cargador y no el formulario que
+ *   la mandó — la misma regla que `guardarAgente` con los `.md` de los subagentes.
+ * - **No toca la clave.** El alta escribe nombre y URL; la credencial va por su camino de
+ *   siempre (`guardarCredencial`, `auth.json`, modo 0600), que es el único mensaje del
+ *   cable que la lleva.
+ */
+export declare function guardarProveedorPersonalizado(declarado: ProveedorDeclarado, operaciones?: OperacionesDeEscritura): {
+    ruta: string;
+    declarado: ProveedorDeclarado;
+};
+/**
+ * Retira un proveedor personalizado del config global. NO se lleva su credencial: eso lo
+ * hace quien llama, con `borrarCredencial`, porque es el otro fichero y el otro permiso —
+ * y una clave huérfana en `auth.json` es una clave que ya no se puede mandar a ninguna
+ * parte, pero sigue siendo un secreto en disco.
+ */
+export declare function borrarProveedorPersonalizado(slug: string, operaciones?: OperacionesDeEscritura): {
+    ruta: string;
+    borrado: boolean;
+};
+/** Guarda la preferencia estética junto al proyecto; nunca en el config global de la cuenta. */
+export declare function guardarTemaDeProyecto(raiz: string, tema: string): {
+    ruta: string;
+    tema: string;
+};
+/** El modelo que este proyecto usa, sea cual sea el global. Nunca lleva claves. */
+export declare function guardarModelosDeProyecto(raiz: string, papel: Papel, id: string): {
+    ruta: string;
+    id: string;
+};
+/**
+ * La rama ORIGEN del proyecto: de la que se baja y contra la que se compara.
+ * Va dentro de `cloudstudio`, junto a la URL y al proyecto, porque es identidad del
+ * remoto y no una preferencia del usuario.
+ */
+export declare function guardarRamaDeProyecto(raiz: string, rama: string): {
+    ruta: string;
+    rama: string;
+};
+/**
+ * El modo pertenece al proyecto, no a la cuenta: una carpeta puede trabajarse sin red
+ * aunque la anterior se abriera desde CloudStudio. OAuth queda siempre fuera de aquí.
+ */
+export declare function guardarModoDeProyecto(raiz: string, modo: "offline" | "cloud"): {
+    ruta: string;
+    modo: "offline" | "cloud";
+};
+/**
+ * Los conectores MCP (IXCODE-11) que este proyecto usa, del catálogo de `core/conectores.ts`.
+ * La lista se REEMPLAZA entera —fusionarla elemento a elemento no tiene un significado
+ * único, a diferencia de un objeto—, y el resto del fichero se conserva igual que en
+ * `guardarModoDeProyecto`.
+ */
+export declare function guardarConectoresDeProyecto(raiz: string, ids: string[]): {
+    ruta: string;
+    conectores: string[];
+};
+/**
+ * El modo con que nacen las sesiones nuevas de este proyecto (IXCODE-31). `undefined` QUITA la
+ * clave (vuelve a mandar el global); `supervisado` SÍ se escribe: en un proyecto es una
+ * elección que pisa a un global autónomo, no la omisión.
+ */
+export declare function guardarModoDeEscrituraDeProyecto(raiz: string, modo: ModoDeEscritura | undefined): {
+    ruta: string;
+    modoDeEscritura: ModoDeEscritura | undefined;
+};
+/**
+ * El gestor de tareas vinculado a este proyecto (IXCODE-11): a qué conector, sitio y
+ * proyecto remoto. `undefined` QUITA la clave del fichero en vez de dejarla vacía o nula
+ * —un `gestorDeTareas: {}` sería una forma más de dato incompleto que `validar` tendría
+ * que rechazar en cada lectura—, misma mecánica que `guardarEntornoDeProyecto`.
+ */
+export declare function guardarGestorDeProyecto(raiz: string, gestor: VinculoGuardado | undefined): {
+    ruta: string;
+    gestorDeTareas: VinculoGuardado | undefined;
+};
+/**
+ * El proyecto de Stitch vinculado a este proyecto (`core/stitch.ts#DisenoVinculado`). `undefined` QUITA la clave, la
+ * mecánica de `guardarGestorDeProyecto`.
+ */
+export declare function guardarDisenoDeProyecto(raiz: string, diseno: DisenoVinculado | undefined): {
+    ruta: string;
+    disenoVinculado: DisenoVinculado | undefined;
+};
+/**
+ * Guarda solo el endpoint MCP: OAuth nunca vive dentro del proyecto.
+ *
+ * Fusiona sobre `cloudstudio`, no lo reemplaza entero: un `/connect-studio` posterior
+ * (nueva URL, o la misma) no puede borrar en silencio la `rama` o el `proyecto` que ya
+ * se habían fijado — la próxima sincronización compararía contra la rama equivocada.
+ */
+export declare function guardarCloudStudioDeProyecto(raiz: string, url: string, scopes?: readonly string[]): {
+    ruta: string;
+    url: string;
+    scopes: string[];
+};
+/**
+ * A qué entorno de `~/.xonecode/settings.json` pertenece este proyecto.
+ *
+ * Se guarda ADEMÁS de `cloudstudio.url`, nunca en su lugar: la URL es lo que leen
+ * `crearSincronizador` (`cli/main.ts`) y todo lo que cuelga de él, y conservarla es lo que
+ * hace literalmente cierto que la sincronización no se toca. El `entorno` añade la
+ * referencia que hacía falta para leer el juego de credenciales correcto
+ * (`porEntorno[id]`, `agent/cloudstudio/cloudstudioMcp.ts`) en vez de reautenticar bajo `legado`.
+ *
+ * Misma mecánica que `guardarCloudStudioDeProyecto`: fusión sobre el objeto CRUDO y
+ * escritura atómica, para no borrar lo que ya hubiera en el fichero.
+ */
+export declare function guardarEntornoDeProyecto(raiz: string, entorno: string | undefined): {
+    ruta: string;
+    entorno: string | undefined;
+};
+/** Guarda la identidad del proyecto remoto, sin mezclarla con el token OAuth. */
+export declare function guardarProyectoCloudStudioDeProyecto(raiz: string, proyecto: {
+    id: string;
+    nombre: string;
+}): {
+    ruta: string;
+    proyecto: {
+        id: string;
+        nombre: string;
+    };
+};
+/**
+ * El bloque `cloudstudio` del proyecto que hay AHORA en disco, leído por su raíz.
+ *
+ * Existe porque quien decide si las escrituras se auto-aprueban no puede mirar
+ * `FuentesDeEleccion.proyecto`: en la consola WEB ese campo no se rellena nunca —el
+ * vestíbulo sirve muchos proyectos y las fuentes se construyen una vez al arrancar
+ * (`web/servidor/arranque.ts`)—, así que la guarda de «esto sube a CloudStudio» habría
+ * dado `undefined` para todos los proyectos, incluidos los conectados. Un fallo abierto y
+ * mudo, que es el peor sitio donde tenerlo.
+ *
+ * Se relee en cada consulta a propósito: es un fichero que el propio alta escribe a mitad
+ * de sesión, y una copia en memoria diría «offline» de un proyecto que acaba de conectarse.
+ */
+export declare function cloudstudioDelProyecto(raiz: string): ConfigDeFichero["cloudstudio"];
+/**
+ * El modo con que nacen las sesiones nuevas de ESTE proyecto (IXCODE-31), leído por la RAÍZ: en
+ * la consola web `FuentesDeEleccion.proyecto` no se rellena nunca (la trampa que ya resolvió
+ * `cloudstudioDelProyecto`). Sin poder leerlo, `undefined`: manda el global, que es lo que
+ * pasaría sin la clave.
+ */
+export declare function modoDeEscrituraDelProyecto(raiz: string): ModoDeEscritura | undefined;
+export declare function cargar(raiz: string): {
+    config: {
+        proyecto?: ConfigDeFichero;
+        global?: ConfigDeFichero;
+    };
+    auth: Auth;
+    rutas: Array<{
+        ruta: string;
+        existe: boolean;
+        procedencia: Procedencia | "auth";
+    }>;
+    avisos: Aviso[];
+};
+/**
+ * Las claves ya presentes en el entorno MANDAN: `auth.json` no las machaca.
+ *
+ * La tabla vive en `core/modelos.ts` y aquí solo se reexporta, para no romper a quien la
+ * importa de este módulo (`agent/config/authEnDisco.ts`). Hubo cuatro copias —dos de ellas en
+ * `cli/`, para que `cli/` no tirase de `agent/` por un mapa de cuatro líneas— y habían
+ * divergido; en `core/`, que es datos puros, los dos lados pueden tirar del mismo sitio.
+ */
+export { VARIABLES_POR_PROVEEDOR } from "../../core/modelos.js";
+/**
+ * Pone la credencial en el entorno del proceso, y NADA más: sin tocar disco.
+ *
+ * Existe para poder PROBAR una clave antes de escribirla —`CatalogoModelos` la lee de
+ * `process.env`, así que sin esto no hay forma de preguntarle al proveedor si sirve— y es
+ * la misma operación que `guardarCredencial` (`agent/config/authEnDisco.ts`) hace al final de su
+ * escritura. Devuelve `false` para un proveedor sin variable (Ollama local): ahí no hay
+ * nada que aplicar y decir que sí sería mentir.
+ */
+export declare function aplicarCredencialAlProceso(proveedor: Proveedor, clave: string): boolean;
+/**
+ * Vuelca las credenciales en `process.env` y devuelve los proveedores que SÍ se
+ * aplicaron. Las que ya estaban en el entorno se dejan intactas y no se cuentan.
+ * `ollama` no tiene variable: no aparece en el mapa y se ignora.
+ */
+export declare function aplicarAuth(auth: Auth): string[];

package/dist/agent/config/crearProyecto.d.ts

@@ -0,0 +1,20 @@
+/**
+ * La escritura del esqueleto en el disco del usuario.
+ *
+ * QUÉ se escribe lo decide `core/esqueleto.ts` (puro, probado sin disco); AQUÍ
+ * solo se ejecuta, al estilo de `agent/config/configEnDisco.ts`. La regla dura es la
+ * misma que en todo xonecode: **el disco es del usuario**, así que un fichero
+ * que ya exista no se pisa — se salta y se declara en el informe. Un proyecto
+ * a medias se completa en la siguiente corrida; un fichero del usuario
+ * destruido no se recupera.
+ */
+import { type DatosDelProyecto } from "../../core/esqueleto.js";
+export interface InformeDeCreacion {
+    /** Ficheros escritos, como rutas relativas a la raíz. */
+    creados: string[];
+    /** Ficheros que ya existían y NO se han tocado. */
+    saltados: string[];
+    /** Carpetas del runtime (creadas ahora o ya existentes). */
+    carpetas: string[];
+}
+export declare function crearProyecto(raiz: string, datos: DatosDelProyecto): InformeDeCreacion;

package/dist/agent/config/diagnosticoDeNodeEnMaquina.d.ts

@@ -0,0 +1,44 @@
+import { type DiagnosticoDeNode } from "../../core/diagnosticoDeNode.js";
+/**
+ * Las medidas de `core/diagnosticoDeNode.ts` en la máquina de verdad. Cada una con su tope, y ninguna devuelve una ruta:
+ * los motivos salen de `motivoDeFallo` (el `code`, nunca el mensaje de Node). Las dependencias se inyectan para que el
+ * test componga el diagnóstico sin lanzar nada.
+ */
+/** Más que esto es «no contesta»: son `--version`, `--help` y una validación de una carpeta vacía. */
+export declare const TOPE_DEL_DIAGNOSTICO_MS = 20000;
+export interface DependenciasDelDiagnostico {
+    plataforma?: NodeJS.Platform;
+    arquitectura?: string;
+    versionDeNode?: string;
+    ahora?: () => Date;
+    /** Un proceso corto: resuelve con su salida, RECHAZA con un código distinto de 0 (como `execFile`). */
+    ejecutar?: (programa: string, args: readonly string[], opciones: {
+        shell: boolean;
+        entorno?: Record<string, string>;
+    }) => Promise<{
+        stdout: string;
+    }>;
+    /**
+     * El entorno de la shell de los AGENTES (`entornoDeShell`, con los scripts de las skills en el PATH): se mide con ÉL y no
+     * con el del servidor. Medido en Windows: el diagnóstico daba «node» en verde con el PATH del servidor mientras el de los
+     * agentes estaba roto («node: command not found»).
+     */
+    entornoDeAgente?: () => Record<string, string>;
+    scripts?: () => {
+        nombre: string;
+        ruta: string;
+    }[];
+    simulador?: () => {
+        programa: string;
+        previos: string[];
+    };
+    versionDeXoneLinter?: () => string | undefined;
+    claude?: () => string | undefined;
+    versionDelSdk?: () => string | undefined;
+    /** El Node con que se lanzan los scripts en Windows (por omisión, el del servidor). */
+    nodeDelServidor?: string;
+    /** El navegador para medir la maqueta (`exportarPdf.ts#navegadorParaImprimir`). */
+    navegador?: () => string | undefined;
+}
+/** Mide todo y compone la foto. Nunca lanza: lo que falla es una línea en rojo con su motivo. */
+export declare function medirDiagnosticoDeNode(deps?: DependenciasDelDiagnostico): Promise<DiagnosticoDeNode>;

package/dist/agent/config/ecoDeRazonamiento.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Devolverle a DeepSeek el `reasoning_content` que su API exige y el cliente tira.
+ *
+ * ## El problema, con las dos citas
+ *
+ * DeepSeek: «for requests carrying the `tools` parameter, the `reasoning_content` must be
+ * fully passed back to the API in all subsequent requests — even for turns where the model
+ * did not perform a tool call. If your code does not correctly pass back
+ * `reasoning_content`, the API will return a 400 error».
+ *
+ * Y `@langchain/openai` 1.5.5 no lo devuelve NUNCA: lo captura al entrar
+ * (`additional_kwargs.reasoning_content`) y lo tira al salir, por los dos conversores.
+ * Un agente manda siempre `tools`, así que pensar + agente = 400 en cuanto la conversación
+ * avanza. Visto en un turno real reventando dentro de un subagente.
+ *
+ * ## Por qué a nivel HTTP y no envolviendo el cliente
+ *
+ * Porque la conversión de mensajes es INTERNA a `ChatOpenAI`: no hay método que
+ * sobrescribir ni middleware que la alcance —un middleware ve los mensajes de LangChain,
+ * no el cuerpo que sale—. Lo que sí es una costura declarada es `configuration.fetch`, que
+ * el SDK de OpenAI acepta y documenta.
+ *
+ * Y tiene una ventaja sobre parchear la dependencia: **el contrato HTTP es lo más estable
+ * que hay**. Este repo ya ha visto a langchain mover un gancho (`beforeAgent` →
+ * `beforeModel`) y a deepagents cambiar una lista de claves en el mismo día; el cuerpo de
+ * `/chat/completions` no se mueve.
+ *
+ * ## Cómo se empareja
+ *
+ * Por el **id de la tool call**, que es único y lo genera el servidor. Cuando una respuesta
+ * trae razonamiento y tool calls, se guarda `id → reasoning_content`; cuando una petición
+ * posterior reenvía ese mismo mensaje de asistente, se le vuelve a pegar. No hace falta
+ * entender la conversación: el id es la identidad.
+ *
+ * **Límite declarado**: un mensaje de asistente SIN tool calls no tiene con qué
+ * emparejarse y no se le devuelve el eco. En un bucle de agente ése es el mensaje FINAL
+ * —después no hay más peticiones de ese hilo—, así que en la práctica no se reenvía. Si
+ * algún día se reenviara, el síntoma sería el mismo 400 de antes y no algo peor.
+ */
+/** Cuántos razonamientos se recuerdan. Una sesión larga no puede crecer sin tope. */
+export declare const TOPE_DE_ECOS = 400;
+export interface MemoriaDeEco {
+    /** Apunta lo que trajo una respuesta. */
+    recordar(id: string, razonamiento: string): void;
+    /** Lo que se guardó para ese id, si consta. */
+    buscar(id: string): string | undefined;
+    readonly tamaño: number;
+}
+/** Un mapa con tope, que descarta lo más viejo. Un `Map` de JS conserva el orden de alta. */
+export declare function crearMemoriaDeEco(tope?: number): MemoriaDeEco;
+interface MensajeDeSalida {
+    role?: string;
+    reasoning_content?: string;
+    tool_calls?: Array<{
+        id?: string;
+    }>;
+}
+/**
+ * Le vuelve a pegar el razonamiento a los mensajes de asistente de una petición.
+ *
+ * Puro y sobre el objeto ya parseado: así se prueba sin red y sin SDK. No toca nada que no
+ * sea un asistente con tool calls, y **no pisa un `reasoning_content` que ya venga** — si
+ * algún día el cliente empieza a mandarlo, esto deja de hacer falta solo.
+ */
+export declare function conEcoDeRazonamiento(cuerpo: {
+    messages?: MensajeDeSalida[];
+}, memoria: MemoriaDeEco): {
+    messages?: MensajeDeSalida[];
+};
+/**
+ * Saca de una respuesta NO streameada lo que haya que recordar.
+ *
+ * Devuelve los pares en vez de escribirlos: así la función es pura y el test no necesita
+ * una memoria de pega para comprobar qué se extrajo.
+ */
+export declare function ecosDeRespuesta(cuerpo: unknown): Array<[string, string]>;
+/**
+ * Lo mismo para un flujo SSE, que es el caso REAL: el turno streamea siempre —el
+ * `_streamResponseChunks` de la dependencia mete `stream: true` en el payload sea cual sea
+ * la bandera del constructor, y eso ya está medido en este repo—.
+ *
+ * Se va acumulando el `delta.reasoning_content` y el primer `tool_call.id` que aparezca;
+ * al cerrar el flujo se tiene el par. **Los ids llegan en trozos**: en SSE un `tool_call`
+ * se parte en varios deltas y solo el primero trae el `id`, así que se guarda el primero
+ * que no venga vacío y no se sobrescribe.
+ */
+export declare function acumuladorDeEcoSse(): {
+    linea(linea: string): void;
+    ecos(): Array<[string, string]>;
+};
+/**
+ * El `fetch` que restaura el eco, para `configuration.fetch` del cliente de OpenAI.
+ *
+ * **No bloquea ni bufferiza el flujo.** La respuesta se parte en dos con `tee()`: una
+ * copia sale intacta hacia el SDK y la otra se lee en segundo plano solo para apuntar el
+ * razonamiento. Bufferizar aquí convertiría el streaming en no-streaming y se notaría en
+ * pantalla; leer la misma copia dos veces no se puede.
+ *
+ * **Y nada de esto puede tumbar una petición**: cada parte va en su `try`. Si el cuerpo no
+ * se deja parsear, se manda tal cual y el peor caso es el 400 que ya había — nunca uno
+ * nuevo causado por esto.
+ */
+export declare function fetchConEcoDeRazonamiento(memoria: MemoriaDeEco, fetchBase?: typeof fetch): typeof fetch;
+export {};

package/dist/agent/config/entorno.d.ts

@@ -0,0 +1,83 @@
+export interface Entorno {
+    raiz: string;
+    /** `app.xml` es la fuente y no un artefacto: es lo que distingue un proyecto XOne. */
+    esProyectoXone: boolean;
+    colecciones: number;
+    /** `X.xml` con un `X.xne` al lado: vistas aplanadas que Studio genera. */
+    vistasAplanadas: string[];
+    /**
+     * Un repo git da el diff y el deshacer gratis; si no, hay que copiar la raíz antes de
+     * tocar nada.
+     *
+     * **No basta con mirar si hay un `.git` al lado.** Medido: `lab/` no tiene `.git` propio
+     * y sin embargo está dentro de un work tree cuya raíz está VARIOS niveles por encima —
+     * el proyecto de un usuario metido en un monorepo se declararía «sin git» y se copiaría
+     * sin necesidad. Se le pregunta a git, que es quien lo sabe.
+     *
+     * `raizRepo` se conserva porque cuando NO coincide con `raiz` el diff abarca más que el
+     * proyecto, y eso hay que decirlo antes de prometer un deshacer.
+     */
+    git: EstadoGit;
+    simulador: {
+        ruta: string;
+        responde: boolean;
+    };
+}
+/**
+ * Las vistas aplanadas: todo `X.xml` que tenga un `X.xne` al lado.
+ *
+ * En XOne cada colección existe en dos formas, y **la que se edita es el `.xne`**. La regla
+ * no puede vivir solo en el prompt del ejecutor —un permiso solo protege a quien lo
+ * choca—, así que estos ficheros se le OCULTAN al agente. Ocultarlos y no borrarlos: el
+ * disco es del usuario.
+ *
+ * `app.xml` no tiene hermano `.xne`, así que el propio predicado lo conserva.
+ */
+export declare function vistasAplanadas(rutas: string[]): string[];
+/**
+ * El estado de git respecto al proyecto.
+ *
+ * **`usable` solo exige que HAYA un repo**, y esto es una corrección: antes exigía además
+ * ser la raíz y tener commits. Sobraban las dos, y se descubrió mirando cómo lo hace
+ * opencode y midiéndolo después contra el disco real (ver `DISENO.md` §15):
+ *
+ * - La foto del ANTES se toma con un **índice de git privado** (`GIT_INDEX_FILE`), y
+ *   `write-tree` **no necesita HEAD**: medido sobre un repo con CERO commits, funciona.
+ * - Y funciona desde un **subdirectorio**: se acota con `git add -- .` y las rutas del
+ *   diff se recortan con `prefijo`.
+ *
+ * `esRaiz` y `tieneCommits` se conservan porque `doctor` los cuenta —saber que el repo
+ * abarca más que el proyecto sigue importando para prometer un deshacer— pero ya no
+ * bloquean nada.
+ */
+export interface EstadoGit {
+    dentro: boolean;
+    raizRepo?: string;
+    /** El proyecto ES la raíz del repo (no un subdirectorio de uno más grande). */
+    esRaiz: boolean;
+    /** Hay al menos un commit. NO hace falta para la foto; sí para ramas y worktrees. */
+    tieneCommits: boolean;
+    /** Ruta del proyecto relativa a la raíz del repo (`""` si es la raíz). */
+    prefijo: string;
+    /** ¿Se puede usar git para la foto del ANTES? Basta con que haya repo. */
+    usable: boolean;
+}
+/**
+ * ¿Sirve git para dar el diff y el deshacer de ESTE proyecto?
+ *
+ * Las tres condiciones salen de medir, no de suponer, contra el disco real del usuario:
+ *
+ * 1. **El repo tiene que ser el del PROYECTO.** Medido: los proyectos viven dentro de un
+ *    repo cuya raíz está por encima, con cientos de entradas sin trackear que no tienen nada
+ *    que ver. Un diff de ese repo no habla del proyecto.
+ * 2. **Tiene que haber al menos un commit.** Ese repo está en `main` con CERO commits:
+ *    `git rev-parse HEAD` falla, y sin commit no hay rama de la que partir, ni worktree
+ *    que añadir, ni nada contra lo que diffear.
+ * 3. **Y aunque acotes al subdirectorio, no vale.** Medido: `git status --porcelain -- .`
+ *    desde dentro del proyecto devuelve UNA línea —`?? proyecto_example/`— porque git no
+ *    desciende en directorios sin trackear. O sea que el diff habría dicho «1 fichero
+ *    nuevo» tocara el agente lo que tocara: un fallo MUDO que reporta algo plausible.
+ *    (`--untracked-files=all` lo expande, pero eso no arregla 1 ni 2.)
+ */
+export declare function inspeccionarGit(raiz: string): Promise<EstadoGit>;
+export declare function inspeccionar(raiz?: string): Promise<Entorno>;

package/dist/agent/config/fuentesEnRed.d.ts

@@ -0,0 +1,12 @@
+import type { FuentesPort } from "../../core/ports.js";
+/**
+ * Google Fonts, de verdad, sin clave (lo medido está en `core/fuentes.ts`).
+ *
+ * **El catálogo se pide UNA vez por puerto** y se guarda: son 2,7 MB de un catálogo AJENO que no
+ * cambia en una sesión. No choca con «no cachear» de `xone_navegacion`, que habla del modelo del
+ * PROYECTO. Un fallo no se guarda: la siguiente llamada lo vuelve a intentar.
+ *
+ * Un fallo lleva el CÓDIGO HTTP o la palabra «red», nunca la URL ni el cuerpo remoto (mismo trato
+ * que `iconosEnRed`). `fetch` entra por parámetro para probarlo sin conexión.
+ */
+export declare function fuentesEnRed(llamar?: typeof fetch, topeMs?: number): FuentesPort;

package/dist/agent/config/gemini.d.ts

@@ -0,0 +1,5 @@
+import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+/** Cliente de Gemini que adapta los esquemas de tools al formato de su API. */
+export declare class ChatGoogleGenerativeAICompatible extends ChatGoogleGenerativeAI {
+    bindTools(...args: Parameters<ChatGoogleGenerativeAI["bindTools"]>): import("@langchain/core/runnables").Runnable<import("@langchain/core/language_models/base").BaseLanguageModelInput, import("langchain").AIMessageChunk<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>>, import("@langchain/google-genai").GoogleGenerativeAIChatCallOptions>;
+}

package/dist/agent/config/iconosEnRed.d.ts

@@ -0,0 +1,10 @@
+import type { IconosPort } from "../../core/ports.js";
+/**
+ * Iconify, de verdad (IXCODE-18). Los mismos datos que usa `better-icons`, pero llamando a la API
+ * directamente: el binario no lo puede ejecutar ningún especialista, y una dependencia global
+ * que instalar es un fallo del entorno que no merece la pena.
+ *
+ * Un fallo lleva el CÓDIGO HTTP o la palabra «red», nunca la URL ni el cuerpo remoto (mismo trato
+ * que `ErrorCatalogoModelos`). `fetch` entra por parámetro para probarlo sin conexión.
+ */
+export declare function iconosEnRed(llamar?: typeof fetch, topeMs?: number): IconosPort;

package/dist/agent/config/identidadEnDisco.d.ts

@@ -0,0 +1,27 @@
+/**
+ * El `user_id` de DeepSeek leído del login de CloudStudio que hay en ESTA máquina.
+ *
+ * La regla (qué token, cómo se normaliza) es pura y vive en `core/identidadDeProveedor.ts`;
+ * aquí solo se decide DE QUÉ ENTORNO se lee y se toca el disco.
+ *
+ * **Qué entorno**, en este orden:
+ *  1. El del proyecto, resuelto EXACTAMENTE como lo resuelve la sincronización
+ *     (`entorno` del `config.json`, y si falta, `entornoDeUrl` sobre su `cloudstudio.url`,
+ *     y si tampoco, `legado`): la persona que baja y sube ese proyecto es la que está
+ *     delante, y una segunda regla para lo mismo acabaría eligiendo otro juego de tokens.
+ *  2. Sin CloudStudio en el proyecto, el PRIMER entorno registrado en `settings.json` con
+ *     una identidad legible, y luego `legado`. Es determinista y está declarado: quien tiene
+ *     sesión en dos servidores sale con el id del primero.
+ *
+ * **Se lee en cada construcción de un modelo, no se captura**: el login puede hacerse con
+ * la consola abierta, y un valor capturado al arrancar dejaría esa sesión sin id para
+ * siempre. Es un `readFileSync` de un JSON pequeño contra una petición de segundos.
+ *
+ * **Nunca lanza.** Un fichero roto o ausente es «no consta», y entonces el campo no viaja:
+ * DeepSeek funciona igual sin él, y un turno caído por no poder ponerle nombre sería
+ * cambiar una ventaja por una avería.
+ *
+ * El hash no va a ningún evento, traza ni `.jsonl`: es un dato de la PETICIÓN, no del turno.
+ */
+import type { FuentesDeEleccion } from "../../core/modelos.js";
+export declare function userIdDeDeepSeekEnDisco(fuentes: FuentesDeEleccion): string | undefined;

package/dist/agent/config/modelos.d.ts

@@ -0,0 +1,77 @@
+import type { ModelosPort, Papel } from "../../core/ports.js";
+import { type FuentesDeEleccion, type Proveedor, type ProveedorDeclarado } from "../../core/modelos.js";
+import { type CapacidadesVivas, type ClaseDeTrabajo, type Esfuerzo, type Pensamiento } from "../../core/esfuerzo.js";
+/**
+ * Construye el modelo de cada papel. NO lleva la marca de doble: es real.
+ *
+ * Los clientes se construyen PEREZOSAMENTE, al pedir el papel: `describe` solo llama a
+ * `descripcion()`, y construir cuatro clientes para imprimir un texto obligaría a tener
+ * las claves puestas para poder mirar la configuración — justo lo que este comando evita.
+ */
+export declare class Modelos implements ModelosPort {
+    private readonly eleccion;
+    /**
+     * Los proveedores personalizados, y es una FUNCIÓN y no una lista a propósito.
+     *
+     * `fuentes` se lee UNA vez, al arrancar el proceso, así que una lista capturada aquí
+     * dejaba muerto el flujo que el usuario hace primero: dar de alta un proveedor en
+     * Ajustes, ponerle la clave, elegir su modelo y hablar — y el turno reventaba con «no
+     * está dado de alta; añádelo en Ajustes», que es justo lo que acababa de hacer. Quien
+     * construye pasa `proveedoresPersonalizados` (`agent/config/configEnDisco.ts`), que relee el
+     * config global; sin nada, se cae a lo que trajera `fuentes`, que es lo que había.
+     *
+     * Del `config.json` GLOBAL y de ningún otro: la regla la impone `core/config.ts` al
+     * validar, y aquí no se vuelve a mirar el del proyecto ni por descuido.
+     */
+    private readonly personalizados;
+    /**
+     * Lo que el servidor ya sabe de un modelo porque se lo PREGUNTÓ, y entra por aquí en vez
+     * de consultarse dentro.
+     *
+     * Hoy solo Ollama: sus capacidades se piden con `POST /api/show`, que es asíncrono y toca
+     * la red, mientras que construir un modelo es síncrono —`paraPapel` devuelve el cliente,
+     * no una promesa— y lo llama el grafo en mitad de un turno. Son las dos cadencias que ya
+     * declara `contextos.ts` sobre el `max_input_tokens` del catálogo vivo, y la salida es la
+     * misma que con los proveedores personalizados: una FUNCIÓN que quien construye rellena
+     * con lo que ya midió, en vez de una consulta escondida aquí dentro.
+     *
+     * **Ausente es la dirección segura**: sin capacidades, `nivelesDeEsfuerzo` no afirma nada
+     * de un modelo de Ollama y el parámetro no se manda. Eso importa porque pedirle pensar a
+     * un modelo que no piensa NO es una respuesta peor — medido, `ministral-3:3b` contesta
+     * `"ministral-3:3b" does not support thinking` y el turno se cae.
+     */
+    private readonly capacidades;
+    /**
+     * El esfuerzo de la SESIÓN, que es el que vale cuando quien pide un modelo no dice otro.
+     *
+     * Va en el constructor y no en cada llamada porque así los diez llamadores de
+     * `paraPapel` —el turno, el juez, el aumentador, el juez visual— no cambian ni una línea:
+     * la sesión ya reconstruye `Modelos` cuando el usuario toca algo (es como funciona
+     * `/modelo`), así que el sitio donde esto entra ya existe.
+     *
+     * Un subagente que fije el SUYO gana, porque `paraModelo` recibe el nivel explícito.
+     */
+    private readonly esfuerzoDeLaSesion;
+    /**
+     * El `user_id` que DeepSeek usa para separar a las personas de una misma cuenta
+     * (`core/identidadDeProveedor.ts` explica por qué hace falta con claves distintas).
+     *
+     * **Por omisión es el lector REAL** (`userIdDeDeepSeekEnDisco`), y no `undefined`: un
+     * parámetro opcional que nadie pasa es el patrón de fallo de este repo en su forma más
+     * limpia —el `Calificador`—, y aquí hay diez `new Modelos(` en producción. Así los diez
+     * quedan cableados sin tocar ninguno, y lo que se pasa a mano es la EXCEPCIÓN (un test).
+     * Es una función y se llama en cada construcción: el login puede llegar con la consola
+     * abierta.
+     */
+    private readonly identidad;
+    constructor(fuentes?: FuentesDeEleccion, personalizados?: () => readonly ProveedorDeclarado[], capacidades?: (proveedor: Proveedor, modelo: string) => CapacidadesVivas | undefined, esfuerzo?: Esfuerzo, identidad?: () => string | undefined);
+    paraPapel(papel: Papel, esfuerzo?: Esfuerzo, clase?: ClaseDeTrabajo, pensamiento?: Pensamiento): unknown;
+    /**
+     * Un modelo concreto por su «proveedor/modelo». `parsear` es la MISMA función que valida
+     * `--modelo` y `/modelo`, no una copia: un id mal escrito en el `.md` de un agente tiene
+     * que fallar igual y con el mismo mensaje que uno mal escrito en la línea de comandos.
+     */
+    paraModelo(id: string, esfuerzo?: Esfuerzo, clase?: ClaseDeTrabajo, pensamiento?: Pensamiento): unknown;
+    idDePapel(papel: Papel): string;
+    descripcion(): Record<Papel, string>;
+}