xonecode 0.38.41 → 0.39.2

package/dist/core/adjuntos.d.ts

@@ -0,0 +1,77 @@
+/**
+ * El mime de un adjunto, por su EXTENSIÓN.
+ *
+ * Es literalmente la MISMA tabla que la de los artefactos y se reexporta en vez de
+ * copiarse: dos tablas de extensiones son dos tablas que divergen, y el criterio ya está
+ * argumentado ahí (por extensión y no olfateando los bytes, porque un PNG lleva ceros en su
+ * cabecera; y lo que no está en la tabla es `undefined`, que es «no lo sé» y no «es
+ * binario»).
+ */
+export { mimeDeArtefacto as mimeDeAdjunto } from "./artefactos.js";
+/**
+ * Dónde caen en DISCO los adjuntos que una persona anexa en el CHAT de una sesión (IXCODE-7):
+ * `.xonecode/sesiones/<id>/adjuntos/`, HERMANA de `artefactos/`. A diferencia de los de una tarea
+ * (`~/.xonecode/tareas/<id>/adjuntos/`), una sesión ya tiene carpeta en el proyecto, y `.xonecode`
+ * no entra en git ni sube a CloudStudio. `segmentoSeguro`: el id llega del cliente.
+ */
+export declare function carpetaDeAdjuntosDeSesion(raiz: string, id: string): string;
+/** El prefijo virtual. Con barra final: `CompositeBackend` la exige para no reconstruir
+ *  `//nombre` fuera de la raíz montada — la misma trampa medida con `/skills/`. */
+export declare const RUTA_ADJUNTOS = "/adjuntos/";
+/**
+ * El nombre de la tool que mete un adjunto en el PROYECTO (`agent/grafo/incorporarAdjunto.ts`).
+ *
+ * Vive aquí, en un módulo neutral, y no junto a la tool: la aprobación va por NOMBRE de tool en
+ * los dos motores, así que lo necesitan `perfiles.ts` (el HITL), `interrupts.ts` (la tarjeta) y
+ * las capacidades de TrueForge — y la tool importa `perfiles.ts` para reaplicar sus permisos.
+ * Declarada al lado de la tool, esas importaciones cerrarían un ciclo de VALOR
+ * (`src/ciclos.test.ts`). Y un literal repetido en cuatro sitios es cuatro sitios donde divergir.
+ */
+export declare const NOMBRE_INCORPORAR_ADJUNTO = "incorporar_adjunto";
+export declare function nombreDeAdjuntoAceptable(nombre: string): boolean;
+/** Lo que se sabe de un adjunto para poder nombrarlo. La forma de `AdjuntoDeTarea`
+ *  (`core/tareas.ts`) reducida a lo que este texto usa. */
+export interface AdjuntoNombrable {
+    nombre: string;
+    bytes: number;
+    mime?: string;
+    /**
+     * Lo que el harness DESCOMPRIMIÓ de un `.zip` al guardarlo (`core/zipDeAdjunto.ts`), con el nombre
+     * relativo a la carpeta de adjuntos (`x/screen.png`). Ausente si no es un zip o no se extrajo.
+     */
+    contenido?: readonly AdjuntoNombrable[];
+}
+/**
+ * La petición del turno con el inventario de los adjuntos detrás.
+ *
+ * **Existe porque montar la carpeta no basta.** El agente no explora `/adjuntos/` por su
+ * cuenta: es una raíz virtual que ninguna instrucción suya nombra, así que un encargo que no
+ * la mencione deja los ficheros ahí sin que nadie los abra. Y no se puede confiar en que lo
+ * diga el ENCARGO: el encargo lo redacta el aumentador —que puede haber fallado, y entonces
+ * es el texto crudo de la persona— o lo edita quien crea la tarea, y las dos cosas pueden
+ * borrar la única mención. Así que se añade al MANDAR el turno, que es el único momento en
+ * que se sabe lo que hay en disco. Es el mismo reparto que `peticionDeFeedback`
+ * (`web/servidor/corredorDeTareas.ts`): el texto de la persona, y detrás lo que el código
+ * sabe.
+ *
+ * **Sin adjuntos no toca nada.** Nombrar una carpeta que no se ha montado sería mandarle al
+ * agente a un sitio que no existe — el «control sin dato detrás» de siempre, aquí en forma
+ * de prompt.
+ *
+ * **Y dice la limitación de las imágenes** (§2 del diseño: que el agente VEA una imagen es
+ * multimodal y es otra tanda). Solo si hay alguna: el aviso pegado a un `.md` sería ruido.
+ * Prometerle que «mira» la captura y que la lea como bytes es la peor clase de mentira aquí,
+ * porque quien se la cree es el modelo y contestará que la ha mirado.
+ *
+ * **`de` distingue de DÓNDE viene el adjunto** (IXCODE-7), porque el resto de la frase cambia
+ * con el origen: uno de TAREA lo anexó quien la creó, antes de que el agente exista; uno de
+ * MENSAJE lo anexa la persona EN el chat, a mitad de conversación, y además dice cómo llevarlo
+ * al proyecto (`incorporar_adjunto`, que pasa por la aprobación) — sin esa línea, el orquestador
+ * no tiene forma de saber que delegar «pon este icono en el menú» necesita nombrar el adjunto Y
+ * el destino. Y dice a QUIÉN: la tool solo la montan los especialistas de motor propio (un hijo
+ * externo corre en otro proceso, sin tools nuestras ni `/adjuntos/`), así que «quien escribe la
+ * tiene» era falso para un `developer-xone` de Claude Code. Omisión `"tarea"`: el llamador de
+ * las tareas (`corredorDeTareas.ts`, con dos argumentos) no cambia de texto; el del chat
+ * (`vestibulo.ts`) pasa `"mensaje"`.
+ */
+export declare function conAdjuntos(peticion: string, adjuntos: readonly AdjuntoNombrable[], de?: "tarea" | "mensaje"): string;

package/dist/core/agentes.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Los subagentes como DATOS: qué es uno, cómo se lee de un fichero y cómo se compone su
+ * prompt. TypeScript puro — leer el disco es cosa de `agent/subagentes/agentesEnDisco.ts`.
+ *
+ * Hasta ahora los cuatro especialistas (`agent/grafo/perfiles.ts`) vivían a fuego en un
+ * `Record`, y su prompt lo componía `xoneAgent.ts#promptDe` con un `nombre === "planner"`
+ * dentro. Eso ya estaba señalado como provisional ahí mismo («los prompts pasan a ficheros
+ * `.md` en la fase 9»); esto es esa fase, y con ella los cuatro dejan de ser un caso
+ * especial: son los mismos ficheros que puede escribir el usuario, sembrados la primera vez.
+ *
+ * **Lo que NO sale del fichero, y es deliberado.** Las reglas de XOne se anteponen SIEMPRE,
+ * desde código, a todo subagente venga de donde venga (`REGLAS_XONE`). Un subagente que no
+ * sepa que XOne ignora en silencio lo desconocido escribirá un atributo inventado y no dará
+ * error — dará un bug mudo, que es la razón de ser de este producto. Poder borrarlas
+ * editando un `.md` convertiría el invariante en una preferencia; es el mismo principio por
+ * el que los avisos de honestidad son código y no prompt (`core/bitacora.ts`).
+ */
+import { type Esfuerzo, type Pensamiento } from "./esfuerzo.js";
+/** De qué está hecho un subagente. Los tres van al MISMO sitio: la lista de deepagents. */
+export type Motor = "modelo" | "claude-code" | "codex" | "opencode";
+export declare const MOTORES: readonly Motor[];
+export interface Agente {
+    /**
+     * Sale del NOMBRE DEL FICHERO, no del frontmatter. Dos razones: la unicidad la garantiza
+     * el sistema de ficheros en vez de una comprobación nuestra que hay que acordarse de
+     * hacer, y renombrar el agente es renombrar el fichero — sin dos sitios que puedan
+     * discrepar sobre cómo se llama.
+     */
+    nombre: string;
+    /**
+     * **Es un prompt, no una etiqueta.** Es el texto que el orquestador lee para decidir
+     * cuándo delegar en este subagente: una descripción vaga hace que no se use nunca, o que
+     * se use para todo. Obligatoria y no vacía por eso.
+     */
+    descripcion: string;
+    motor: Motor;
+    /**
+     * Qué modelo usa este subagente. Ausente = el que le tocaría por omisión, y lo que eso
+     * significa depende del MOTOR — que es justo por lo que este campo vale para los tres:
+     *  - `modelo`: `proveedor/modelo` de los nuestros; ausente, el del papel `trabajo`.
+     *  - `claude-code`: un alias del producto (`opus`, `sonnet`, `haiku`, `fable`) o un id
+     *    entero; ausente, el que Claude Code use por su cuenta.
+     *  - `codex`: un id de los que su propio `model/list` devuelve; ausente, el suyo.
+     *
+     * Este campo se RECHAZABA con los dos motores externos, con el argumento de que ahí el
+     * modelo lo elige el agente. Era falso y está medido: el SDK de Claude Code acepta
+     * `options.model` —y documenta esos alias— y el `ThreadStartParams` de Codex acepta
+     * `model`. Rechazarlo dejaba fuera lo que el usuario quería decidir de verdad: con qué
+     * modelo corre cada especialista.
+     */
+    modelo?: string;
+    /**
+     * Cuánto tiene que PENSAR su modelo antes de contestar.
+     *
+     * Es un ajuste DEL modelo y por eso va pegado a él: qué niveles hay depende de cuál esté
+     * puesto, y la mitad de los que este harness ofrece no admiten ninguno (`core/esfuerzo.ts`
+     * tiene la tabla y lo medido). Ausente = no se manda el parámetro, que es lo que hacía
+     * este harness entero hasta ahora.
+     *
+     * **Tiene efecto con `motor: "modelo"` y con `claude-code`**, que lo recibe como `effort` de su SDK
+     * (`PeticionExterna.esfuerzo`; medido en Maset, el desarrollador en Opus pasaba casi todo su tiempo
+     * generando). En Codex y OpenCode el modelo lo construye el hijo con su configuración y un campo
+     * nuestro no llega: declararlo ahí no rompe nada, pero no hace nada, y la ventana de Ajustes lo dice.
+     *
+     * Se valida al APLICARLO y no al leerlo: un nivel que el modelo no admite se omite
+     * (`esfuerzoAplicable`), porque rechazar el `.md` haría desaparecer un subagente que
+     * funciona por un campo que solo afinaba su coste.
+     */
+    esfuerzo?: Esfuerzo;
+    /**
+     * Si su modelo PIENSA antes de contestar: `apagado` o `activo`, aparte del esfuerzo (que es cuánto). Ausente
+     * decide la omisión de la familia del proveedor y la clase de trabajo (`pensamientoPorOmision`); solo se
+     * aplica donde el modelo lo admite (`admiteApagarElPensamiento`), y en otro caso se ignora sin error, como el
+     * esfuerzo. Un valor que no es exactamente uno de los dos se descarta.
+     */
+    pensamiento?: Pensamiento;
+    /** Sin escribir nada. Decide `permisosDe` y si se le monta el HITL. */
+    soloLectura: boolean;
+    /**
+     * Las carpetas del PROYECTO donde este agente SÍ puede escribir, aun siendo de solo
+     * lectura. Rutas virtuales (`/doc/`), separadas por comas.
+     *
+     * Nace del que documenta: su entregable es un manual en `doc/`, y sin esto la única forma
+     * de dárselo era quitarle el `soloLectura` — o sea, abrirle el código entero para que
+     * pudiera escribir un `.md`. Esto separa las dos cosas: puede escribir DONDE se le diga y
+     * en ningún otro sitio.
+     *
+     * **No afloja lo denegado a todo el mundo**: `permisosDe` pone estas filas DETRÁS de
+     * `DENEGADO_SIEMPRE`, y con *first-match-wins* eso mantiene ganando a `/.env`, `/.git` y
+     * `/.xonecode`. Un `.md` puede cambiar el prompt de un agente; no puede concederle leer
+     * la clave del cliente.
+     *
+     * Solo tiene efecto con `soloLectura: true`: quien ya escribe, escribe en todas partes.
+     */
+    escribeEn?: string[];
+    /**
+     * Si puede EJECUTAR comandos en la máquina (la tool `execute` de deepagents).
+     *
+     * **Ausente es que no**, y es lo único que puede significar: es una capacidad, y una
+     * capacidad que se concede por omisión es la que nadie decidió conceder. Cierto solo con
+     * exactamente «true», como `soloLectura` — la trampa del `"false"` de CloudStudio, que
+     * aquí concedería la máquina entera.
+     *
+     * **Lo que concede no es «correr un comando», es la máquina.** Una shell no pasa por
+     * `permisosDe` ni por el `virtualMode`: lee `/.env`, escribe el proyecto sin aprobación y
+     * sale de la raíz. La propia deepagents se niega a fingir lo contrario y LANZA si le pasas
+     * `permissions` junto a un backend ejecutable. Por eso se declara aquí, en el fichero, en
+     * vez de deducirse de nada: lo que no se declara, no se concede.
+     *
+     * **Tiene efecto con `motor: "modelo"` y con `claude-code`** (`admiteEjecucion`). En Claude
+     * Code la shell se abre ESTRECHA: solo los scripts de sus skills, por su nombre y con
+     * argumentos que la shell no reinterpreta (`core/comandoExterno.ts`), con el entorno de
+     * nuestra shell. En OpenCode (la tool retirada) y en Codex (sandbox `read-only`) sigue
+     * cerrada: declararlo ahí no rompe nada, pero no hace nada, y la ventana de Ajustes lo dice.
+     */
+    ejecucion?: boolean;
+    /**
+     * A qué otros especialistas puede LLAMAR él mismo, por nombre (`llama: [device-controller]`). Solo lo honra
+     * TrueForge y solo con el interruptor del bucle del desarrollador encendido: es lo que deja que quien escribe
+     * pruebe su trabajo sin pasar por el orquestador. Un nombre que no está en esta lista NO se le concede.
+     */
+    llama?: string[];
+    /**
+     * De qué otros especialistas ESPERA el fin, por nombre (`espera: [designer-xone]`), cuando el orquestador los
+     * lanza a la vez: no hace ninguna llamada al modelo mientras haya un hilo vivo de esos. Solo lo honra TrueForge.
+     * Existe porque dos escritores en paralelo con una dependencia entre ellos (los recursos gráficos del uno, el
+     * `.xne` que los usa del otro) dejaban recursos sin usar.
+     */
+    espera?: string[];
+    /** Las skills del catálogo que se le cargan, por nombre. */
+    skills: string[];
+    /** El cuerpo del `.md`: sus instrucciones. Puede estar vacío. */
+    instrucciones: string;
+    /** De dónde salió, para poder decirlo en la interfaz y al resolver colisiones. */
+    origen: "proyecto" | "global" | "semilla";
+}
+/**
+ * Las reglas del dominio, iguales para todos y NO editables desde el fichero.
+ *
+ * Están aquí y no repetidas en cada `.md` sembrado por lo mismo que `marca.css` tiene los
+ * colores en un solo sitio: cuatro copias de esto es como se acaba con una que se queda
+ * vieja. Y un agente que el usuario escriba mañana las hereda sin tener que copiarlas.
+ */
+/**
+ * Dónde está cada cosa en un proyecto XOne.
+ *
+ * **No son reglas, es un mapa**, y por eso va aparte de `REGLAS_XONE`: aquello dice lo que no
+ * se puede hacer y esto dice dónde mirar. Existe porque el gasto medido de este harness no son
+ * los ficheros que se leen —181 líneas de XML en una medida real, del orden de 2-3k tokens de
+ * 39k— sino **los viajes que hacen falta para averiguar dónde mirar**: cada uno reenvía el
+ * prompt entero y cuesta miles de tokens. Cuatro líneas que hacen certero el primer `grep`
+ * salen baratas comparadas con una lectura exploratoria de más.
+ *
+ * Lo ve el orquestador **y** cada especialista: desde que el orquestador contesta lo que puede
+ * en vez de delegarlo todo, él es quien más lo necesita, y dejarlo solo en `promptDeAgente`
+ * habría sido escribirlo para quien ya no hace ese trabajo.
+ *
+ * Comprobado contra el esqueleto y contra un proyecto real antes de escribirlo: `app.xml` lleva
+ * `<entry-point>`, `<login-coll>`, `<style url>` e `<include file>`, y las colecciones son
+ * `<coll>` en `.xne`, una por fichero salvo `mappings.xne`, que agrupa varias. Un mapa
+ * inventado sería exactamente el bug mudo que este producto existe para evitar.
+ */
+export declare const MAPA_DEL_PROYECTO: string;
+export declare const REGLAS_XONE: string;
+/** ¿Recibe el núcleo de trabajo? Quien escribe el proyecto entero, o quien conduce el aparato. Regla de DATO. */
+export declare function recibeNucleoDeTrabajo(a: Pick<Agente, "soloLectura" | "ejecucion" | "escribeEn">): boolean;
+/**
+ * ¿Recibe `marcar_criterios_del_plan`? Quien TRABAJA las tareas de un plan: el mismo reparto que el
+ * núcleo de trabajo —de los de serie, `developer-xone`, `designer-xone` y `device-controller`—.
+ *
+ * Solo la llevaba quien ejecuta, y medido en una sesión real el plan no se movió en todo el turno: el
+ * desarrollador llamó tres veces al conductor sin nombrarle el plan, así que el conductor no marcó
+ * nada, y el propio desarrollador reescribió el `TASKS.md` entero al acabar. Quien cierra una tarea
+ * es quien sabe que la cerró. No abre nada: los dos que la ganan ya escriben en `/planes/`
+ * (`permisosDe`), y la tool solo cambia `- [ ]` por `- [x]`. Vive en `core/` porque la usan los DOS motores.
+ */
+export declare function recibeMarcarCriterios(a: Pick<Agente, "soloLectura" | "ejecucion" | "escribeEn">): boolean;
+/**
+ * El prompt completo de un subagente: sus reglas, su descripción y sus instrucciones.
+ *
+ * Las reglas van PRIMERO y las instrucciones al final, en ese orden a propósito: lo último
+ * que lee el modelo es lo que más pesa, y lo que el usuario escribió es lo específico de la
+ * tarea. Las reglas no se pueden perder por ir arriba — son cinco líneas, no un preámbulo
+ * largo del que el modelo se despiste.
+ */
+export declare function promptDeAgente(agente: Agente, skills?: EstadoDeSkills): string;
+/**
+ * Las skills de un agente MÁS las de los agentes a los que llama (`llama`). Para un hijo de Claude Code con ejecución:
+ * corre en otro proceso y no puede llamar a nuestros especialistas, así que lo que haría el de pruebas —desplegar,
+ * recargar, capturar— lo hace él, con las skills y los scripts de ese agente (medido en una tarea de Maset: el
+ * desarrollador en Claude Code no tenía ningún script y no pudo probar nada). Sin repetidos, las suyas primero.
+ */
+export declare function skillsConLasDeQuienLlama(agente: Pick<Agente, "skills" | "llama">, todos: readonly Pick<Agente, "nombre" | "skills">[]): string[];
+/**
+ * Lo que se le dice a un hijo de Claude Code CON ejecución que tenía a quién llamar: no puede, y lo hace él, con su visión
+ * para comparar con la maqueta (al abrir una imagen con `Read`, Claude la ve). `carpeta` es la de artefactos de la
+ * sesión, en disco: ahí guardan sus capturas los scripts y ahí está la maqueta traída de Stitch.
+ */
+export declare function textoDeTrabajoSinLlamar(llama: readonly string[], carpeta: string): string;
+/**
+ * Para un hijo de motor EXTERNO: lo que hacer con una tool de xonecode que su `.md` o su encargo nombren. Medido en Maset:
+ * el desarrollador en Claude Code buscó `validar_fichero_xone` y `comparar_capturas` con `ToolSearch`, y el orquestador
+ * le pedía abrir la maqueta «con describe_image».
+ */
+export declare const HERRAMIENTAS_DEL_EXTERNO: string;
+/**
+ * Dónde están EN EL DISCO las carpetas de la sesión que un encargo nombra por su ruta virtual. Para un hijo de Claude
+ * Code: él ve el disco, y `/artefactos/diseno/screen.jpg` es para él una ruta del sistema, fuera del proyecto. Medido en
+ * Maset: el analista recibió esa ruta y contestó «no he podido leer la maqueta». Las dos carpetas se pueden LEER
+ * aunque no ejecute (`PeticionExterna.lecturas`).
+ */
+export declare function textoDeCarpetasDeLaSesion(artefactos: string, hotswap: string): string;
+/** Qué skills de las que el agente declara existen de verdad en el catálogo, y cuáles no. */
+export interface EstadoDeSkills {
+    suyas: string[];
+    faltan: string[];
+}
+/** Reparte las skills declaradas entre las que hay y las que no. Puro: el catálogo entra. */
+export declare function repartirSkills(agente: Agente, disponibles: ReadonlySet<string>): EstadoDeSkills;
+/**
+ * Por qué ese nombre no vale, o `undefined` si vale. El molde de `motivoDeClaveInaceptable`
+ * y `motivoDeEndpointInaceptable`: una sola función, y el motivo en la voz de quien lo lee.
+ *
+ * **Se aplica al GUARDAR y no al cargar** (`leerCarpetaDeAgentes` solo lo DICE): rechazar al
+ * cargar haría desaparecer un agente que funciona, que es lo contrario de lo que hace el
+ * resto de este módulo. Guardar es el único momento en que hay alguien delante que lo puede
+ * arreglar — y desde que el nombre de un subagente propio se puede cambiar, tiene con qué.
+ */
+export declare function motivoDeNombreInaceptable(nombre: string): string | undefined;
+/**
+ * El nombre que SÍ valdría, para poder ofrecerlo. `undefined` si no se puede proponer nada.
+ *
+ * Existe para que el aviso sea accionable: «renómbralo a `documentador`» se arregla, y «el
+ * nombre no vale» hay que adivinarlo. Los acentos se descomponen con NFD y se les quita la
+ * marca —así `diseñador` sale `disenador` y no `dise-ador`—, que es la diferencia entre una
+ * propuesta que el usuario acepta y una que tiene que corregir.
+ *
+ * Y se COMPRUEBA con la misma función antes de devolverlo: una propuesta que no valdría sería
+ * peor que no proponer nada.
+ */
+export declare function nombreSugerido(nombre: string): string | undefined;
+/** Lo que se pudo leer, y lo que no con su motivo. Nunca se descarta nada en silencio. */
+export interface Lectura {
+    agentes: Agente[];
+    /** Un fichero por línea: qué fichero y qué le pasa. Se dice por consola. */
+    problemas: string[];
+}
+/**
+ * Un agente ya cargado: el fichero, más de QUIÉN es.
+ *
+ * `semilla` no sale del `.md` —no hay forma de escribirlo ahí, y está bien: sería un campo
+ * que el usuario podría mentir— sino de comparar lo que hay en disco con lo que sembramos
+ * nosotros (`agentesEnDisco.ts#marcarSemilla`). Por eso vive en un tipo aparte de `Agente`,
+ * que es lo que `leerAgente` devuelve de un fichero.
+ *
+ * TRES estados y no un booleano, porque la pantalla hace tres cosas distintas con ellos y
+ * un `{deSerie, modificado}` admitiría la combinación imposible «no es de serie pero está
+ * modificado»:
+ *
+ * | valor | qué es | qué se puede hacer con él |
+ * |---|---|---|
+ * | ausente | un subagente del usuario | borrarlo |
+ * | `"intacta"` | de serie, tal como lo entregamos | nada: no hay nada que restaurar |
+ * | `"modificada"` | de serie, con el prompt afinado | restaurar el de serie (pisa lo suyo) |
+ *
+ * Y un de serie NO se borra: ver `restaurarAgente`. Borrarlo no devolvía el de serie —la
+ * marca recuerda que se entregó y no se resiembra—, así que era perderlo para siempre.
+ */
+/**
+ * La ficha con la que el ORQUESTADOR conoce a un especialista: su descripción más lo que
+ * SABE HACER y lo que DEVUELVE.
+ *
+ * **Por qué hace falta, medido en la librería.** deepagents arma la lista de especialistas con
+ * `- ${name}: ${description}` y nada más
+ * (`getTaskToolDescription`/`subagentDescriptions.push`), bajo un encabezado que promete
+ * «Available agent types **and the tools they have access to**» — una promesa que su cuerpo no
+ * cumple. O sea que lo único que el orquestador sabe de su equipo es una frase en prosa: no
+ * sabe quién escribe, quién alcanza la máquina ni qué devuelve cada uno. Y con eso no se puede
+ * ENGRANAR nada: componer un pipeline exige conocer las capacidades y qué entra y sale de cada
+ * pieza.
+ *
+ * **Se DERIVA de lo que el `.md` ya declara**, nunca se escribe a mano. Así un subagente del
+ * usuario trae su ficha solo y no hay una segunda lista que se quede vieja — que es el fallo
+ * que este repo ya tiene anotado para la regla de los diagramas, la única escrita a pelo.
+ *
+ * Y la frase del usuario va DELANTE y entera: es lo que él quiso decir, y esto solo la
+ * completa con lo que el código sabe y él no tiene por qué repetir.
+ */
+/**
+ * La skill que TRAE OpenUI (`skills/openui-builder/`). Vive aquí porque la nombran dos lados: la
+ * ficha que el orquestador lee para delegar y la capability que monta la tool
+ * (`agent/motores/trueforge/capacidades.ts`), y dos literales serían dos sitios donde el nombre
+ * puede cambiar sin que el otro se entere.
+ */
+export declare const SKILL_DE_OPENUI = "openui-builder";
+export declare function fichaDeAgente(agente: Agente, opciones?: {
+    conIconos?: boolean;
+    conFuentes?: boolean;
+}): string;
+export interface AgenteCargado extends Agente {
+    semilla?: "intacta" | "modificada";
+}
+/** Lo que `cargarAgentes` contesta: como `Lectura`, pero sabiendo de quién es cada uno. */
+export interface Carga {
+    agentes: AgenteCargado[];
+    problemas: string[];
+}
+/**
+ * Un `.md` con frontmatter, a `Agente`. Devuelve el motivo en vez de lanzar: un fichero
+ * roto no puede tumbar el arranque de la consola — se salta, se dice cuál y por qué, y los
+ * demás siguen. Es la misma postura que `sesiones.ts` con una línea corrupta del `.jsonl`.
+ */
+export declare function leerAgente(nombre: string, contenido: string, origen: Agente["origen"]): {
+    agente: Agente;
+} | {
+    error: string;
+};
+/**
+ * Junta las dos carpetas: el de PROYECTO gana sobre el global con el mismo nombre.
+ *
+ * Misma precedencia que los modelos (`core/modelos.ts`), y por lo mismo: un «revisor de
+ * XOne» se quiere en todos los proyectos, y un «experto en esta app» solo en uno — y el
+ * segundo tiene que poder pisar al primero sin borrarlo.
+ */
+export declare function fusionarAgentes<T extends Agente>(global: readonly T[], proyecto: readonly T[]): T[];
+/**
+ * Los campos del `.md` que la ventana de Ajustes NO enseña ni edita: no viajan por el cable, así que un guardado desde
+ * allí llegaba sin ellos y `escribirAgente` los BORRABA en silencio. Medido en Maset: el diseñador perdió `escribeEn`
+ * —lo único que lo confina a `icons/` y `fonts/`— y cualquier edición del desarrollador le quitaba `llama` y `espera`,
+ * el bucle con el de pruebas. El guardado los toma del agente que ya había (`conLoQueLaVentanaNoEdita`).
+ */
+export declare const CAMPOS_FUERA_DE_LA_VENTANA: readonly ["escribeEn", "llama", "espera", "pensamiento"];
+/**
+ * El agente que llega de la ventana, con los campos que ella no edita tomados del que ya había. Lo que SÍ trae el
+ * cable manda: el día que la ventana edite uno de ellos, su valor gana sin tocar esto. Sin `previo` (un alta), tal cual.
+ */
+export declare function conLoQueLaVentanaNoEdita<T extends Partial<Agente>>(previo: Partial<Agente> | undefined, nuevo: T): T;
+/**
+ * Un agente con SHELL y con `escribeEn` promete un confinamiento que no tiene: la shell no pasa por `permisosDe`, y a
+ * quien ejecuta se le quitan `write_file`/`edit_file`, así que lo que escriba lo escribe por la shell, en cualquier
+ * carpeta y sin aprobación. Medido en Maset: el diseñador con la casilla marcada escribió sus SVG con `echo` en cmd.exe.
+ * Se DICE al cargar (no se rechaza: haría desaparecer un subagente que funciona).
+ */
+export declare function avisoDeEjecucionConCarpetas(a: Pick<Agente, "ejecucion" | "escribeEn">): string | undefined;
+/** El `.md` de un agente, para escribirlo. Lo inverso de `leerAgente`. */
+export declare function escribirAgente(agente: Agente): string;
+/**
+ * Con qué motores `ejecucion: true` concede de verdad una shell: el nuestro, y Claude Code con la
+ * shell ESTRECHA de `core/comandoExterno.ts`. Codex y OpenCode, no. La usan la ficha con la que el
+ * orquestador conoce a su equipo, Ajustes (su copia declarada) y la sesión: tres sitios que tienen
+ * que contestar lo mismo.
+ */
+export declare function admiteEjecucion(motor: Motor): boolean;

package/dist/core/analisisDeSesion.d.ts

@@ -0,0 +1,63 @@
+/**
+ * El análisis PREVIO de un chat o de una tarea, para la pestaña Soporte: qué salió mal, dicho
+ * con reglas de código y sin llamar a ningún modelo.
+ *
+ * ## Lo que lee, y lo que NO lee
+ *
+ * Solo datos ESTRUCTURADOS: el `tipo` de cada acto, sus campos (`verde`, `errores`,
+ * `detalles[].nombre`, `detalles[].error`, `consumo.ventana`), las líneas de la traza por su
+ * `tipo`, los registros de fallos y el estado de la tarea. **Nunca el `texto` de un acto
+ * `sistema`**: su clase viaja con el acto precisamente para que nadie la deduzca de la
+ * redacción (`core/actos.ts`), y una regla que buscara «no ha corrido» en un aviso se
+ * rompería el día que alguien cambie la frase, sin que nada avisara.
+ *
+ * ## Límites declarados
+ *
+ * - **Una escritura que se RECHAZÓ no consta.** El acto `sistema` de clase `permiso` es una
+ *   escritura aplicada SIN preguntar (modo autónomo); del rechazo no queda acto estructurado.
+ * - **«Escribió y no se verificó» puede ser un artefacto**: la línea de tool no dice a qué
+ *   ruta escribió como dato, así que un `write_file` a `/artefactos/` cuenta igual. Por eso es
+ *   un aviso y lo dice.
+ * - Solo ve lo que ESTE chat dejó con su id: las líneas de traza y de fallos sin `chat` no
+ *   entran aquí (`core/paqueteDeSoporte.ts`).
+ */
+import type { Acto } from "./actos.js";
+import type { RegistroDeFallo } from "./fallos.js";
+import type { Tarea } from "./tareas.js";
+export type GravedadDeHallazgo = "info" | "aviso" | "error";
+export type GravedadDeAnalisis = "ok" | "aviso" | "error";
+export type ReglaDeAnalisis = "turno-con-error" | "verificador-en-rojo" | "escritura-sin-verificar" | "tools-fallidas" | "escrituras-sin-preguntar" | "pregunta-sin-contestar" | "corte-por-tope" | "tool-en-bucle" | "contexto-cerca-del-tope" | "fallo-registrado" | "turno-sin-terminar" | "tarea-requiere-atencion" | "juez-no-verde";
+export interface HallazgoDeAnalisis {
+    regla: ReglaDeAnalisis;
+    gravedad: GravedadDeHallazgo;
+    mensaje: string;
+    /** El turno, contado desde 1 por cada mensaje de usuario. Ausente = no es de un turno. */
+    turno?: number;
+}
+export interface AnalisisDeSesion {
+    gravedad: GravedadDeAnalisis;
+    hallazgos: HallazgoDeAnalisis[];
+}
+export interface EntradaDeAnalisis {
+    actos: readonly Acto[];
+    /** Las líneas de `traza-tools.jsonl` de ESTE chat, ya parseadas. */
+    trazas?: readonly Record<string, unknown>[];
+    /** Los registros de `fallos.jsonl` de ESTE chat. */
+    fallos?: readonly RegistroDeFallo[];
+    tarea?: Pick<Tarea, "estado" | "motivo" | "veredicto">;
+    /** El chat tiene un turno EN VUELO: el último turno sin cerrar no es un problema todavía. */
+    enVuelo?: boolean;
+    /** El tope de contexto del modelo de la sesión, si se sabe. Sin él la regla no corre. */
+    topeDeContexto?: number;
+}
+/** Cuántas llamadas IGUALES seguidas son un bucle y no una lectura en varias partes. */
+export declare const LLAMADAS_IGUALES_PARA_BUCLE = 4;
+/** A partir de qué fracción del tope la ventana está «cerca»: queda poco antes de resumir. */
+export declare const FRACCION_DE_CONTEXTO_CERCA = 0.9;
+/** Las tools que ESCRIBEN en el proyecto (las que llevan HITL, `CLAUDE.md`). */
+export declare const TOOLS_QUE_ESCRIBEN: ReadonlySet<string>;
+/** Lo que cabe de un mensaje de error en un hallazgo: se reconoce, no se reproduce. */
+export declare const TOPE_DE_MENSAJE = 200;
+/** La gravedad del conjunto: la del peor hallazgo. Un `info` solo no es un problema. */
+export declare function gravedadDe(hallazgos: readonly HallazgoDeAnalisis[]): GravedadDeAnalisis;
+export declare function analizarSesion(entrada: EntradaDeAnalisis): AnalisisDeSesion;

package/dist/core/aprendido.d.ts

@@ -0,0 +1,41 @@
+/**
+ * **Lo APRENDIDO en un proyecto**, de un encargo para los siguientes: cómo entrar en la app (usuario y clave), qué hay que
+ * pulsar para llegar a una pantalla, una trampa del aparato. Lo apunta el agente con `apuntar_aprendizaje` y el HARNESS
+ * se lo pone delante en cada encargo siguiente, sin depender de que se acuerde de leerlo.
+ *
+ * Existe por una medida: en Maset el agente redescubría en cada encargo que había que pulsar «Entrar» con el usuario
+ * `08006`. La memoria del proyecto (`MEMORIA_PROYECTO.md`) existía, pero solo se escribía si al agente se le ocurría.
+ *
+ * Vive en `.xonecode/aprendido.json` del proyecto: no sube a CloudStudio ni entra en los commits, y **no viaja en un
+ * paquete de soporte** (`SECRETOS_QUE_NO_VIAJAN`), porque puede llevar una contraseña. Puro: el disco va en `agent/`.
+ */
+export declare const FICHERO_DE_APRENDIDO = "aprendido.json";
+export declare const NOMBRE_APUNTAR_APRENDIZAJE = "apuntar_aprendizaje";
+export interface Aprendizaje {
+    /** De qué va, corto y estable: el mismo tema se SUSTITUYE (`cómo entrar en la app`). */
+    tema: string;
+    texto: string;
+    /** Cuándo se apuntó, ISO. */
+    cuando: string;
+    /** Quién lo apuntó (el agente). */
+    quien?: string;
+}
+/** Cuántos se guardan: al pasar, se va el más viejo. Todos van delante de cada encargo, así que pocos y útiles. */
+export declare const TOPE_DE_APRENDIZAJES = 30;
+export declare const TOPE_DE_TEMA = 80;
+export declare const TOPE_DE_TEXTO = 600;
+/** Por qué no se puede apuntar, o `undefined`. */
+export declare function motivoDeAprendizajeInaceptable(a: {
+    tema: string;
+    texto: string;
+}): string | undefined;
+/** La lista con el nuevo: el mismo tema se SUSTITUYE (y pasa al final, el más reciente); pasado el tope, fuera el más viejo. */
+export declare function conAprendizaje(lista: readonly Aprendizaje[], nuevo: Aprendizaje): Aprendizaje[];
+/** El fichero leído: lo que no se entienda se deja fuera, entrada a entrada; un fichero roto es una lista vacía. */
+export declare function interpretarAprendido(texto: string): Aprendizaje[];
+/** El bloque que el harness pone delante de cada encargo. Sin nada apuntado, nada. */
+export declare function bloqueDeAprendido(lista: readonly Aprendizaje[]): string | undefined;
+/** Cuándo apuntar, para quien tiene la tool: una tool sin un «cuándo» no se usa. */
+export declare const USO_DE_APUNTAR_APRENDIZAJE: string;
+/** Para un hijo de motor EXTERNO, que no tiene la tool: lo cuenta al volver y quien le llamó lo apunta. */
+export declare const USO_DE_APRENDIDO_EXTERNO: string;

package/dist/core/artefactos.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Dónde caen en DISCO los artefactos de una sesión: `.xonecode/sesiones/<id>/artefactos/`.
+ *
+ * Vive en `core/` y no en `web/servidor/sesiones.ts` porque lo necesitan los dos lados —el
+ * que borra la sesión y el que monta el backend—, y `cli/` no puede importar de `web/`. Es
+ * lo que ya son las rutas de `core/settings.ts`: una regla de dónde va cada cosa.
+ *
+ * Pasa por `segmentoSeguro` por lo mismo que el `.jsonl`: el id llega del cliente por HTTP,
+ * y sin esa guarda un `"../../.env"` compondría una ruta fuera de `sesiones/`.
+ *
+ * Convive con `<id>.jsonl` sin chocar —uno es fichero con extensión, otra es carpeta—, así
+ * que no hay nada que mover. Meter el transcript dentro (`<id>/sesion.jsonl`) es una mudanza
+ * aparte, con su respaldo de lectura para las sesiones que ya existen.
+ */
+export declare function carpetaDeArtefactosDeSesion(raiz: string, id: string): string;
+/** El prefijo virtual. Con barra final: `CompositeBackend` la exige para no reconstruir
+ *  `//nombre` fuera de la raíz montada — la misma trampa medida con `/skills/`. */
+export declare const RUTA_ARTEFACTOS = "/artefactos/";
+export declare function esRutaDeArtefacto(ruta: string | undefined): boolean;
+export declare function esBasuraDeArtefacto(relativa: string): boolean;
+export declare function artefactoFueraDeSitio(ruta: string): string | undefined;
+/**
+ * ¿Es una ruta de `/artefactos/` que ha llegado al backend del PROYECTO?
+ *
+ * Solo puede pasar si el montaje FALTA: con él, el `CompositeBackend` desvía `/artefactos/` a la
+ * carpeta de la sesión antes de que el proyecto la vea. Y que falte no es teórico: el motor
+ * TrueForge no recibía carpeta en la consola de terminal ni en `run --real`, y un `write_file` de
+ * `/artefactos/panel.html` acabó en `artefactos/panel.html` de la app del cliente —y SIN
+ * aprobación, porque por una ruta de artefacto no se pregunta (`perfiles.ts#seDetieneEn`)—.
+ * Medido el 24-09-2026. Así que la guarda del proyecto la rechaza: si el montaje vuelve a faltar,
+ * el fallo es un error que el modelo lee, no un fichero en la app.
+ *
+ * El primer segmento y sin distinguir mayúsculas, como `artefactoFueraDeSitio`. El precio es el
+ * mismo que allí y ya se pagaba: una carpeta `artefactos/` en la raíz del proyecto no se puede
+ * escribir con el agente —con el montaje puesto, tampoco se podía—.
+ */
+export declare function artefactoSinMontar(ruta: string): boolean;
+/** El nombre que se le enseña a una persona: el último segmento y nada más. */
+export declare function nombreDeArtefacto(ruta: string): string;
+/**
+ * Lo que hay que poner detrás de la carpeta para ABRIR el fichero: la ruta sin `/artefactos/`.
+ *
+ * **No es `nombreDeArtefacto` y confundirlas era un botón muerto.** Aquélla contesta «cómo se
+ * llama esto para una persona» y se queda con el último segmento, que es lo correcto para una
+ * tarjeta. Para abrirlo hace falta el camino ENTERO: un `unzip` deja un ÁRBOL bajo la carpeta
+ * de la sesión —una maqueta descomprimida vive en `/artefactos/diseno/screen.png`— y con el
+ * basename el `join` apuntaba a `<carpeta>/screen.png`, que no existe. El síntoma era un
+ * «no pude abrir» sobre un fichero que estaba ahí y que la propia foto había anunciado.
+ *
+ * **No lleva guarda de travesía y no la necesita**: quien la llama ha pasado antes por
+ * `esRutaDeArtefacto`, que ya exige que cada segmento sea llano y que ninguno sea `.` ni `..`.
+ * Ponerla aquí sería un segundo sitio donde decidir sobre una ruta, que es la única forma en
+ * la que estas guardas se han roto nunca.
+ */
+export declare function rutaRelativaDeArtefacto(ruta: string): string;
+export declare function mimeDeArtefacto(nombre: string): string | undefined;
+/**
+ * Lo que se sabe de un artefacto recién escrito.
+ *
+ * No lleva el CONTENIDO, y esa ausencia es la de siempre: por aquí pasa lo que acaba en el
+ * transcript y en el cable, y un panel de `artifacts-builder` son cientos de kilobytes de
+ * HTML. Lleva lo que deja decir «hay un diagrama de 42 KB y se llama así» y lo que deja ir a
+ * buscarlo: la ruta virtual, con la que se lee después.
+ */
+export interface Artefacto {
+    /** La ruta virtual, tal como la escribió el agente (`/artefactos/flujo.html`). */
+    ruta: string;
+    /** El último segmento, para enseñarlo. */
+    nombre: string;
+    /** Por extensión, o ausente si no se sabe. Nunca se adivina. */
+    mime?: string;
+    /** Tamaño en bytes de lo que se escribió. */
+    bytes: number;
+}