xonecode 0.38.44 → 0.39.2

package/dist/agent/grafo/proyecto.d.ts

@@ -0,0 +1,450 @@
+import { type DispositivoDeLaSesion } from "../../core/dispositivoDeSesion.js";
+import { FilesystemBackend } from "deepagents";
+import { type ValidarContenido } from "./validacionXone.js";
+import { type Montaje } from "./skills.js";
+import { type Artefacto } from "../../core/artefactos.js";
+/**
+ * El backend del proyecto: confinado, y sin las vistas aplanadas.
+ *
+ * **`virtualMode: true` no es configurable.** Medido contra deepagents 1.13.2: con el
+ * default (`false`) el backend LEYÓ una ruta absoluta de fuera de la raíz. La propia
+ * librería lo dice de su default — «absolute paths and `..` can bypass rootDir».
+ *
+ * Y sin shell: el `execute` de deepagents solo aparece si el backend sabe ejecutar, así que
+ * éste es el que deja a un especialista SIN esa tool. El que sí la tiene es
+ * `backendDelProyectoConShell`, y quién se lleva cuál lo decide `ejecucion` en el `.md`.
+ */
+export declare function backendDelProyecto(raiz: string): FilesystemBackend;
+/**
+ * El mismo backend, pero que además EJECUTA — el de un subagente con `ejecucion: true`.
+ *
+ * Es la pieza que enciende la tool `execute` de deepagents: el middleware la registra solo
+ * cuando «el backend resuelto sabe ejecutar», y lo que decide eso es `isSandboxBackend`, que
+ * mira que haya un `execute` y un `id` NO vacío (medido en la librería: `id !== ""`).
+ *
+ * **Lo que `virtualMode` NO hace aquí, y hay que tenerlo delante.** Confina las tools de
+ * FICHERO, no los comandos: un `cat ../../otro` del shell sale de la raíz igual. Lo mismo
+ * vale para `permisosDe`, y la propia librería se niega a fingir lo contrario — usar
+ * `permissions` con un backend ejecutable **lanza `ConfigurationError`** («permissions are
+ * not enforced on execute because shell commands can access any path regardless of
+ * path-based rules»). O sea que conceder ejecución es conceder la máquina, y por eso se
+ * declara en el `.md`, se ve en cada evento y lo lleva un solo subagente.
+ *
+ * **El entorno se pasa ENTERO y a mano, nunca `inheritEnv`.** Con `inheritEnv: true` la
+ * shell hereda `process.env`, donde `guardarCredencial` escribe las claves de API a
+ * propósito; un `printenv` las dejaría en el contexto. Lo que se pasa lo decide
+ * `core/shellDeAgente.ts#entornoDeShell`, que es puro y tiene test.
+ *
+ * **El límite declarado, heredado de la librería**: el tope sigue siendo de RELOJ
+ * (`TOPE_DE_COMANDO_S`, pasado como `timeoutS`), no de silencio, al revés que
+ * `TOPE_SIN_SALIDA_MS` de `agent/dispositivos/`. Por eso lo que no termina —un emulador— va al
+ * fondo desde la propia orden, y eso lo dice la skill. Al vencer, `crearExecuteCancelable`
+ * (`agent/grafo/ejecucionCancelable.ts`) manda `SIGKILL` al ÁRBOL vía `matarGrupoReal` —
+ * `process.kill(-pid)` en POSIX, `taskkill /T /F` en Windows—: un nieto no sobrevive.
+ */
+export declare function backendDelProyectoConShell(raiz: string, entorno: Record<string, string>, 
+/**
+ * La señal del TURNO en curso, ya resuelta desde fuera (`sesionTrueforge.ts`). Ausente —el
+ * caso de deepagents, que no la forwardea nunca— y `execute` se comporta exactamente como
+ * antes: sin cancelación interactiva, pero YA con el kill de árbol al vencer el timeout.
+ */
+senalDelTurno?: () => AbortSignal | undefined): FilesystemBackend;
+/**
+ * El aparato de la sesión, leído AHORA del mismo fichero que leen los scripts (la variable
+ * `XONECODE_DISPOSITIVO` de la shell apunta aquí). Lo usa la guarda del `execute`
+ * (`core/shellDeAgente.ts#motivoDeOtroAparato`, IXCODE-32): se lee en cada comando porque la
+ * persona puede cambiar de aparato con la sesión abierta. Sin carpeta de artefactos, o sin
+ * fichero, no hay aparato elegido.
+ */
+export declare function lectorDelDispositivoDeSesion(artefactos: string | undefined): () => DispositivoDeLaSesion | undefined;
+/**
+ * El entorno con el que corre la shell de ESTE proyecto.
+ *
+ * Una sola llamada para que el montaje no sea una composición dentro de `construirAgente`:
+ * ahí lo doblan todos los tests y la regla —qué claves se quitan, qué rutas se añaden—
+ * quedaría escrita y sin probar. La decisión es pura y vive en `core/shellDeAgente.ts`; lo
+ * que aporta esto es de dónde salen los tres ingredientes.
+ *
+ * Las skills se leen del disco en cada construcción, igual que `skillsMontables` en el
+ * backend y que `cargarAgentes`: una skill instalada con la consola abierta no alcanza a la
+ * sesión en curso, que es el límite ya anotado en CLAUDE.md y no uno nuevo.
+ */
+export declare function entornoDeLaShellDelProyecto(raiz: string, artefactos?: string, 
+/**
+ * El buscador de binarios del SDK de Android. Entra por parámetro **solo** para que un test
+ * pueda ver que está montado: esta función toca `process.env` y `existsSync`, así que sin
+ * inyectarlo la composición viviría donde ningún test la alcanza — el patrón de fallo que
+ * este repo lleva contadas nueve veces. En producción no lo pasa nadie.
+ */
+enSdk?: (nombre: string, subcarpeta: string) => string | undefined): Record<string, string>;
+/**
+ * Los SCRIPTS que un agente puede correr por su nombre: los ficheros EJECUTABLES de la carpeta
+ * `scripts/` de las skills que declara (`agente.skills`), en el orden de sus skills. Es la lista
+ * que un agente de Claude Code con ejecución tiene permitida (`core/comandoExterno.ts`); un
+ * `.mjs` sin bit de ejecución no cuenta, porque por su nombre no correría.
+ */
+export declare function scriptsDeLasSkills(raiz: string, skills: readonly string[], plataforma?: NodeJS.Platform): string[];
+/**
+ * Los mismos scripts, con su RUTA. **En Windows no hay bit de ejecución** —Node da `mode` sin él a todo fichero—, así que
+ * allí cuenta un script de Node por su primera línea (`#!/usr/bin/env node`). Medido en la máquina Windows de un usuario:
+ * con el bit como única regla la lista salía VACÍA y el desarrollador en Claude Code se quedaba sin ningún script.
+ */
+export declare function scriptsConRuta(raiz: string | undefined, skills: readonly string[], plataforma?: NodeJS.Platform): {
+    nombre: string;
+    ruta: string;
+}[];
+/**
+ * El tope de reloj de UN comando, en segundos.
+ *
+ * El de la librería son 120 s. Se sube porque aquí los comandos normales son de dispositivo
+ * —un `adb install`, esperar a que un emulador termine de arrancar— y 120 s los corta a
+ * mitad; y no se sube más porque un comando que no vuelve deja el turno colgado hasta aquí.
+ * Lo que de verdad no termina nunca (arrancar un emulador) no se acota con un tope: se manda
+ * al fondo, que es lo que la skill explica.
+ */
+export declare const TOPE_DE_COMANDO_S = 600;
+/**
+ * Añade las skills como una ruta virtual de solo lectura del agente.
+ *
+ * El proyecto del usuario sigue siendo la raíz predeterminada. `/skills` apunta al
+ * catálogo que se distribuye con xonecode: así SkillsMiddleware puede descubrir y
+ * cargar bajo demanda cada `SKILL.md` sin conceder al modelo acceso al repositorio
+ * del harness ni sacarlo de la raíz del proyecto.
+ *
+ * **Y las del USUARIO cuelgan de esa misma ruta, una a una.** Viven en otras dos carpetas
+ * (`~/.xonecode/skills/` y la del proyecto, `agent/grafo/skills.ts`) y tienen que verse como
+ * UNA sola: un subagente declara `skills: [mi-skill]` y eso se traduce a `/skills/mi-skill/`
+ * sin saber de dónde salió el fichero. Una raíz aparte —`/skills-tuyas/`— habría metido de
+ * quién es la skill dentro de su ruta, y entonces cambiarla de carpeta le cambiaría el
+ * nombre al agente.
+ *
+ * Se apoya en que `CompositeBackend` ordena sus rutas **por longitud descendente** y se
+ * queda con la primera que encaja (`sortedRoutes` en deepagents 1.13.2): `/skills/mia/` es
+ * más larga que `/skills/`, así que gana para todo lo que cuelgue de ella. Eso no es una
+ * suposición sobre la librería: lo ata `proyecto.test.ts` contra la librería REAL, que es la
+ * única forma de enterarse el día que cambie.
+ *
+ * **Límite declarado**: un `ls /skills` enseña solo las de serie. `CompositeBackend.ls`
+ * resuelve a UNA ruta y no funde varias, así que las del usuario no salen en ese listado. No
+ * importa para lo que esto hace —`SkillsMiddleware` recibe las rutas una a una, ya
+ * resueltas, y es así como el modelo las descubre— pero un agente que liste esa carpeta a
+ * mano no las verá.
+ */
+/**
+ * Monta la máquina entera bajo `/disco/`, de solo lectura, y contesta bien a quien pegue una
+ * ruta absoluta a pelo.
+ *
+ * El porqué entero está en `core/discoDeLaMaquina.ts`. Aquí, las dos mitades del cableado:
+ *
+ * - **El montaje**: la misma pieza que `/skills/`, `/adjuntos/` y `/planes/` — otra raíz del
+ *   `CompositeBackend`, con su barra final obligatoria. El «solo lectura» no lo pone esto: lo
+ *   pone `permisosDe`, que es donde vive esa decisión para todas las raíces.
+ * - **La REESCRITURA**, que es lo que evita el viaje en balde. Una ruta de máquina escrita a
+ *   pelo (`/Users/…/x.zip`) se resuelve DENTRO del proyecto y vuelve un ENOENT que dice «no
+ *   existe» sobre un fichero que sí existe —y de paso filtra la raíz absoluta del proyecto—.
+ *   Se intercepta antes y se devuelve la ruta buena ya escrita.
+ */
+/**
+ * Contesta bien a una ruta de la MÁQUINA escrita como si fuera del proyecto.
+ *
+ * Sin esto se resuelve DENTRO del proyecto y vuelve un ENOENT que dice «no such file or
+ * directory» sobre un fichero que sí existe —y de paso filtra la raíz absoluta del proyecto—.
+ * Medido: el orquestador concluía que estaba enjaulado y se iba a delegar en el agente con
+ * shell. Aquí se le devuelve el paso siguiente ESCRITO, que es el patrón de `porQueNo`.
+ *
+ * No monta nada y no abre nada: solo sustituye un mensaje que engaña por uno que sirve.
+ */
+export declare function conAvisoDeRutaDeMaquina<T extends object>(backend: T): T;
+export declare function backendConSkills<T extends object>(backend: T, propias?: readonly Montaje[]): T;
+/**
+ * Cuelga `/adjuntos/` de la carpeta que le toque, de solo lectura.
+ *
+ * **La misma pieza que `/skills/` y `/artefactos/`**: otra raíz del `CompositeBackend`. Y de
+ * solo lectura por lo mismo que las skills — son material de ENTRADA, los documentos que
+ * anexó la persona, no ficheros que reescribir. Quien lo deniega es `permisosDe`
+ * (`agent/grafo/perfiles.ts`), incondicionalmente y por patrón: aquí no hay Proxy que
+ * rechace, igual que no lo hay para `/skills/`, porque la denegación que el modelo choca es
+ * la del middleware de permisos y ese es el sitio donde vive la regla.
+ *
+ * **`carpeta` puede ser de DOS orígenes** y a este backend le da igual cuál: la de una TAREA
+ * (`~/.xonecode/tareas/<id>/adjuntos/`, FUERA del proyecto) o, desde IXCODE-7, la del CHAT de
+ * una SESIÓN (`carpetaDeAdjuntosDeSesion`, DENTRO de `.xonecode/`). Las dos evitan git y
+ * CloudStudio, por rutas distintas — el porqué entero está en `core/adjuntos.ts`. Meterlos
+ * DENTRO del proyecto es la tool `incorporar_adjunto`, no esta pieza.
+ *
+ * **La carpeta no se crea aquí**, misma medida que `/artefactos/`: `FilesystemBackend` no
+ * exige que su `rootDir` exista. Quién decide qué `carpeta` llega es
+ * `cli/main.ts#carpetaDeAdjuntosDelEjecutor`, con la MISMA regla para las dos fuentes: **en
+ * la web se monta SIEMPRE**, exista o no la carpeta en disco — la de la tarea, si TRAE
+ * adjuntos (`web/servidor/corredorDeTareas.ts`), y si no, la del CHAT de esa misma sesión
+ * (vacía; una tarea también abre por el ejecutor de la web, y cae a su propia sesión igual
+ * que una persona — inocuo, es su propia carpeta). **En el terminal, nunca**: su hilo no
+ * tiene carpeta de sesión que derivar.
+ */
+export declare function backendConAdjuntos<T extends object>(backend: T, carpeta: string): T;
+/**
+ * Cuelga `/planes/` de `.xonecode/planes/`, en el repo LOCAL.
+ *
+ * El porqué de ese sitio está en `core/planes.ts`. Lo que aporta esto es el montaje, y tiene
+ * las mismas dos trampas que `/artefactos/` y `/skills/`:
+ *
+ *  - **La barra final es obligatoria**: `CompositeBackend` la retira antes de delegar, y sin
+ *    ella reconstruye `//favoritos/PLAN.md`, que `FilesystemBackend` interpreta fuera de su
+ *    raíz.
+ *  - **La carpeta NO se crea al montar**: la crea `FilesystemBackend.write` la primera vez que
+ *    se escribe. Un proyecto en el que nadie ha planificado no tiene por qué tener la carpeta.
+ *
+ * Y una diferencia con los artefactos que es el motivo de que exista: esto **no se anuncia**.
+ * Un artefacto se enseña una vez; un plan se escribe, se lee y se ACTUALIZA por varios
+ * especialistas a lo largo de varios turnos, así que un evento por escritura sería ruido.
+ */
+export declare function backendConPlanes<T extends object>(backend: T, raiz: string): T;
+/**
+ * Cuelga `/artefactos/` de la carpeta de la SESIÓN, fuera del proyecto.
+ *
+ * El porqué está en `core/artefactos.ts`: hoy los diagramas del `mockup` acaban en la raíz
+ * del proyecto y de ahí a git y a CloudStudio. Esto es el mismo mecanismo que `/skills/`
+ * —otra raíz en el `CompositeBackend`— con dos diferencias que importan:
+ *
+ * - **Se puede ESCRIBIR.** `/skills/` está denegada en `permisosDe` porque son instrucciones
+ *   del harness; esta es justamente donde el agente deja lo que produce.
+ * - **Se APUNTA lo que se escribe.** El backend es el único sitio que sabe que una escritura
+ *   ocurrió y cuánto pesó, y un artefacto que nadie nombra es un fichero en una carpeta que
+ *   nadie abre. El Proxy va sobre el sub-backend y no sobre el compuesto: así solo ve lo de
+ *   esta carpeta, sin filtrar las escrituras del proyecto por el mismo sitio.
+ *
+ * La carpeta **no se crea aquí**. Medido contra deepagents: `FilesystemBackend` no exige que
+ * su `rootDir` exista y el `write` lo crea. Crearla al montar dejaría un `artefactos/` vacío
+ * en cada sesión que no dibuja nada, que es la mayoría.
+ */
+export declare function backendConArtefactos<T extends object>(backend: T, carpeta: string, alEscribir: (artefacto: Artefacto) => void): T;
+/**
+ * Cuelga `/large_tool_results/` y `/conversation_history/` al lado de los artefactos de la
+ * sesión — o sea, FUERA del proyecto.
+ *
+ * Son las dos carpetas donde deepagents descarga lo que no cabe en el contexto, y hasta
+ * ahora no estaban montadas: medido, `large_tool_results/call_866999.txt` (26 KB) acabó
+ * dentro del AppDemo del usuario y commiteado. El porqué entero, y por qué la carpeta se
+ * deriva de la de artefactos en vez de recibir su propio parámetro, está en
+ * `core/descargas.ts`.
+ *
+ * La misma pieza que `/skills/`, `/artefactos/` y `/adjuntos/`: otra raíz del
+ * `CompositeBackend`, con la barra final obligatoria y sin crear la carpeta al montar
+ * —`FilesystemBackend` no exige que su `rootDir` exista y el `write` la crea—. Aquí eso
+ * importa más que en las otras: la mayoría de las sesiones no descargan nada, y crearlas al
+ * montar dejaría dos carpetas vacías en cada una.
+ *
+ * **Y no se apunta nada de lo que se escriba, al contrario que `/artefactos/`.** Un
+ * artefacto es una salida para una persona y por eso se anuncia; esto es el andamio del
+ * agente —la salida cruda de una tool que él mismo va a volver a leer— y un evento por cada
+ * una sería ruido en la conversación sobre algo que nadie pidió.
+ */
+export declare function backendConDescargas<T extends object>(backend: T, carpetaDeArtefactos: string): T;
+/**
+ * Cuelga `/hotswap/` al lado de los artefactos de la sesión — o sea, FUERA del proyecto.
+ *
+ * Es donde el script `xone-hotswap` deja lo que saca del contexto: el árbol de controles de
+ * una pantalla, el log del aparato. El porqué entero —y la medida de los 10 volcados de los
+ * que 6 no volvió a abrir nadie— está en `core/hotswap.ts`.
+ *
+ * La misma pieza que `/skills/`, `/artefactos/`, `/adjuntos/` y las dos de descarga: otra
+ * raíz del `CompositeBackend`, con la barra final obligatoria y sin crear la carpeta al
+ * montar. Y **no se anuncia**, igual que las descargas y al contrario que los artefactos:
+ * ésa es exactamente la diferencia que esta carpeta existe para marcar.
+ *
+ * Que esté MONTADA es la otra mitad del arreglo, y no es opcional. El agente tenía la
+ * carpeta del disco en `$XONECODE_ARTEFACTOS` y ninguna ruta virtual con la que volver a
+ * abrir lo que el script le había guardado; en la traza se le ve probando tres rutas —la
+ * absoluta de la máquina incluida— antes de rendirse y leerlo por la shell. Con esto,
+ * `read_file("/hotswap/<nombre>")` funciona y el script puede NOMBRAR esa ruta en su salida.
+ *
+ * No necesita fila en `permisosDe`: los `deny` de ahí son de `write`, así que leer ya está
+ * permitido, y escribir cae bajo el `deny` general — que es lo correcto, porque quien escribe
+ * aquí es una shell, y una shell no pasa por los permisos.
+ */
+export declare function backendConHotswap<T extends object>(backend: T, carpetaDeArtefactos: string): T;
+/**
+ * Envuelve el backend del PROYECTO para que una descarga del agente no pueda aterrizar
+ * dentro.
+ *
+ * Con las dos raíces montadas esto no salta nunca —`CompositeBackend` enruta por prefijo de
+ * TEXTO, sin mirar si la carpeta destino existe (leído en deepagents 1.13.2)—, y ahí está el
+ * sentido: el día que el montaje falte, la escritura falla CERRADO en vez de acabar en la
+ * app del cliente. Es la misma lección que la fila incondicional de `/adjuntos/` en
+ * `permisosDe`, medida por el mismo camino.
+ *
+ * Y como `sinArtefactosEnElProyecto`: **solo `write` y `edit`** —leer o borrar una descarga
+ * mal puesta de antes tiene que seguir funcionando— y el rechazo se DEVUELVE como `{error}`,
+ * nunca se lanza. Leído en deepagents 1.13.2: los tools de fichero hacen
+ * `if (result.error) return result.error`, así que un error devuelto vuelve al modelo y una
+ * excepción se lleva el turno por delante. Aquí quien escribe es la librería y no una tool,
+ * y su hueco en el contexto ya sabe decir «no se pudo guardar»: lanzar reventaría el turno
+ * por una descarga que solo es andamio.
+ */
+export declare function sinDescargasEnElProyecto<T extends object>(backend: T): T;
+/**
+ * El backend con el que el agente ve el proyecto, compuesto entero.
+ *
+ * Vivía dentro de `construirAgente`, y eso dejaba sin probar justo la parte que decide si
+ * las reglas están puestas: los tests de este fichero comprobaban cada envoltorio por
+ * separado y `construirAgente` se simula en todos los suyos, así que **el cableado no lo
+ * miraba nadie**. Una regla que existe y no está montada es peor que no tenerla, porque
+ * hay un test en verde diciendo que sí.
+ *
+ * El orden es lo que hay que leer aquí:
+ * 1. La raíz confinada (`virtualMode`), con la memoria del proyecto expuesta por su ruta
+ *    virtual.
+ * 2. Las dos reglas del PROYECTO: las vistas aplanadas no existen, y un artefacto no se
+ *    puede escribir dentro.
+ * 3. `/skills/` colgada, de solo lectura por `permisosDe`.
+ * 4. Y `/artefactos/` colgada por FUERA, que es lo que hace que escribir ahí no pase por la
+ *    guarda de (2) — son dos raíces distintas del mismo compuesto.
+ * 4b. Y las dos carpetas donde deepagents DESCARGA lo que no cabe en el contexto
+ *    (`/large_tool_results/`, `/conversation_history/`), al lado de los artefactos. Sin
+ *    ellas caían en el proyecto: medido, commiteadas dentro de la app del usuario.
+ * 5. Y `/adjuntos/`, según decida quien llama (ver `backendConAdjuntos`): la misma pieza, de
+ *    solo lectura por `permisosDe`.
+ */
+export declare function backendDeAgente(opciones: {
+    raiz: string;
+    ficheros: ReadonlySet<string>;
+    artefactos?: {
+        carpeta: string;
+        alEscribir: (artefacto: Artefacto) => void;
+    };
+    /**
+     * Presente solo para un subagente con `ejecucion: true` en su `.md`. Cambia la BASE de la
+     * cadena por una que ejecuta, y con eso deepagents le registra la tool `execute`. Ausente
+     * —que es todo el mundo menos uno— la cadena no es ejecutable y `permisosDe` sigue
+     * aplicándose, que es justo lo que la librería prohíbe combinar.
+     */
+    ejecucion?: {
+        entorno: Record<string, string>;
+        senal?: () => AbortSignal | undefined;
+    };
+    /**
+     * La carpeta de los adjuntos que se montan como `/adjuntos/`, si hay alguna: los de una
+     * TAREA o, desde IXCODE-7, los que una persona anexó en el CHAT de esta sesión — a este
+     * backend le da igual cuál (ver `backendConAdjuntos`). Ausente y `/adjuntos/` no se monta;
+     * entonces esa ruta no es nada, y la denegación incondicional de `permisosDe` evita que se
+     * convierta en un fichero del proyecto (medido: sin ella lo era).
+     */
+    adjuntos?: string;
+    /**
+     * Con qué se juzga el contenido antes de escribirlo. Entra por parámetro para poder mirar
+     * la guarda desde fuera sin un parser delante; en producción es `validarConXoneLinter()`.
+     */
+    validar?: ValidarContenido;
+}): FilesystemBackend;
+/**
+ * Anuncia lo que un COMANDO deja en la carpeta de artefactos.
+ *
+ * El evento `artefacto` —«hay un diagrama de 42 KB y se llama así», nunca el contenido— lo
+ * emite hoy el Proxy de `backendConArtefactos`, que envuelve `write` y `edit`. Una shell no
+ * llama a ninguna de las dos: escribe en el disco de verdad. Así que sin esto, una captura
+ * dejada por un script no sale en la pestaña Artefactos ni en el hilo, y el subagente tendría
+ * que decir «he dejado una captura» sin que nada lo respalde — que es la clase de afirmación
+ * que este harness no quiere.
+ *
+ * **Se compara una FOTO de antes con una de después** (ruta relativa → tamaño + mtime) en
+ * vez de fiarse de lo que el comando diga que hizo. Un comando puede escribir tres ficheros,
+ * o ninguno, o pisar el de antes; lo único que lo sabe es la carpeta.
+ *
+ * **Y la foto es RECURSIVA, porque un `unzip` deja un ÁRBOL y no un fichero.** Era
+ * `readdirSync` a secas más un `isFile()`, o sea que una carpeta se saltaba entera y con
+ * ella todo lo que llevara dentro. Medido sobre una sesión real: el zip de una maqueta se
+ * descomprimió en `/artefactos/stitch-restaurantes/stitch_screen_complex/` y salieron CERO
+ * anuncios — los tres ficheros estaban en el disco y no existían para nadie, sin pestaña
+ * Artefactos (solo existe si hay alguno) y sin tarjeta en el hilo. Es el mismo fallo que la
+ * carpeta sin crear, un escalón más adentro. No se baja por un ENLACE: `Dirent.isDirectory()`
+ * es falso para uno, y lo que cuelgue de él no es lo que esta sesión produjo.
+ *
+ * Lo que la recursión hace aparecer también se filtra, y las dos cribas son la misma idea:
+ * **no anunciar lo que acaba en una tarjeta muerta**. `esRutaDeArtefacto` es la barrera que
+ * el LECTOR aplica, así que un nombre que él rechazaría (`Diseño final.png`) pintaría una
+ * fila cuyo único final es un 403; y `esBasuraDeArtefacto` retira el `__MACOSX/._x.png` que
+ * un zip de Finder arrastra, que tiene la extensión del bueno y doscientos bytes dentro.
+ *
+ * **Y la carpeta se CREA aquí, antes de correr el comando.** Es la excepción a «no se crea
+ * al montar», y la pagó una captura: `$XONECODE_ARTEFACTOS` la crea `FilesystemBackend.write`
+ * la primera vez que el agente escribe un artefacto por una TOOL, y una shell no pasa por
+ * ahí — así que en una sesión que no había dibujado nada, el `writeFileSync` del script de
+ * captura reventaba con ENOENT (reproducido) y el modelo se replegaba a dejar el `.png` en
+ * la raíz del proyecto, que es justo lo que la regla existe para impedir. El sitio es este y
+ * no el script: quien SABE que va a correr una shell y DÓNDE está la carpeta es el harness,
+ * y arreglarlo en el script lo dejaría arreglado en uno de cinco —y en ninguna skill del
+ * usuario—, que es el patrón de fallo de siempre. Se crea solo cuando hay ejecución, así que
+ * una sesión de los otros cuatro especialistas sigue sin carpeta vacía.
+ */
+/**
+ * La FOTO recursiva de la carpeta de artefactos: ruta relativa → `tamaño:mtime`. La comparación de
+ * dos fotos es lo que anuncia lo que dejó un comando (`anunciarArtefactosDeLaShell`, y el hijo de
+ * Claude Code con ejecución). No baja por enlaces.
+ */
+export declare function fotoDeArtefactos(carpeta: string): Map<string, string>;
+/** Lo que cambió entre dos fotos, como artefactos que se pueden anunciar (sin lo que el lector rechazaría ni la basura de un zip). */
+export declare function artefactosNuevos(antes: Map<string, string>, despues: Map<string, string>): Artefacto[];
+export declare function anunciarArtefactosDeLaShell<T extends object>(backend: T, carpeta: string, alEscribir: (artefacto: Artefacto) => void): T;
+/**
+ * Expone la memoria del proyecto sin abrir la carpeta interna `.xonecode`.
+ *
+ * Los permisos siguen denegando esa carpeta completa (puede contener configuración), pero
+ * esta única ruta virtual permite al agente conservar decisiones aprobadas entre sesiones.
+ */
+export declare function exponerMemoriaDeProyecto<T extends object>(backend: T): T;
+/**
+ * El motivo con el que se rechaza escribir un artefacto en el proyecto.
+ *
+ * Mismo criterio que `porQueNo`: rechazar y EXPLICAR. Un error seco haría que el modelo
+ * probara otra ruta —o que diera el trabajo por hecho—; diciéndole la ruta buena, corrige a
+ * la primera. Y nombra las tres consecuencias porque son el porqué: sin ellas, «usa otra
+ * carpeta» se lee como una preferencia de estilo.
+ */
+export declare const porQueNoAhi: (ruta: string, destino: string) => string;
+/**
+ * Envuelve el backend del proyecto para que un artefacto NO se pueda escribir dentro.
+ *
+ * **Por qué es código y no una frase más en el prompt.** La carpeta buena ya la nombran los
+ * cuatro sitios que el modelo puede leer, y aun así, medido el 2026-09-07 en dos
+ * delegaciones consecutivas del mismo proyecto: la primera escribió
+ * `/artifacts/login_flow.html` —la raíz— y la segunda `/artefactos/diagrama.html`. Con la
+ * instrucción puesta en los cuatro sitios, añadir un quinto no cambia nada; lo que cambia es
+ * que la regla deje de depender de que el modelo la recuerde. Es exactamente el argumento de
+ * `sinVistasAplanadas`, y también el de los avisos de honestidad: en este repo lo que tiene
+ * que cumplirse es código.
+ *
+ * Va sobre el backend del PROYECTO, por dentro del compuesto, así que una escritura en
+ * `/artefactos/` —que es otra raíz montada— no pasa por aquí y no se ve afectada.
+ *
+ * **Solo `write` y `edit`.** Leer un artefacto mal puesto de una sesión anterior tiene que
+ * seguir funcionando: si no, el agente no podría ni mirar lo que hay que mover. Y borrarlo
+ * tampoco se toca — quitar de la app del cliente un diagrama que no debería estar ahí es
+ * justo lo que se quiere poder hacer.
+ */
+export declare function sinArtefactosEnElProyecto<T extends object>(backend: T): T;
+/** ¿Es `ruta` una vista aplanada, teniendo a la vista el conjunto de ficheros del proyecto? */
+export declare function esVistaAplanada(ruta: string, todas: ReadonlySet<string>): boolean;
+/**
+ * El mensaje con el que se rechaza tocar una vista aplanada.
+ *
+ * **Rechazar y explicar, no fallar en seco.** Un «fichero no encontrado» hace que el modelo
+ * pruebe otra ruta, o peor, que dé por hecho que el cambio no hacía falta. Diciéndole dónde
+ * está la fuente puede corregir — pero solo si el mensaje LLEGA, y para eso hay que
+ * devolverlo como `{error}` y no lanzarlo (ver `sinVistasAplanadas`).
+ */
+export declare const porQueNo: (ruta: string) => string;
+/**
+ * Envuelve un backend para que las vistas aplanadas no existan para el agente.
+ *
+ * **Por qué no basta con decirlo en el prompt.** La regla ya vivía ahí en el harness
+ * anterior, solo en el del ejecutor, y falló por donde tenía que fallar: *un permiso solo
+ * protege a quien lo choca*. El planner planificaba sobre el `.xml` y el juez exigía el
+ * cambio ahí — ninguno de los dos podía conocer una regla que vivía en otro prompt.
+ * Retirarlas del backend la convierte en una propiedad del PROYECTO, no de un prompt.
+ *
+ * **Se ocultan, no se borran.** El disco es del usuario. (El harness con MCP sí las
+ * borraba de su copia, pero aquella copia era suya y se tiraba al final.)
+ *
+ * `app.xml` no tiene hermano `.xne`, así que el propio predicado lo conserva: es fuente.
+ */
+export declare function sinVistasAplanadas<T extends object>(backend: T, todas: ReadonlySet<string>): T;

package/dist/agent/grafo/skills.d.ts

@@ -0,0 +1,181 @@
+import { type LecturaDeSkills, type OrigenDeSkill, type Skill } from "../../core/skills.js";
+import type { SkillInfo, SkillsPort } from "../../core/ports.js";
+/**
+ * Las skills en disco: una carpeta por skill, con su `SKILL.md` dentro.
+ *
+ * **Tres raíces, no una.** El porqué de cada una y su precedencia están en
+ * `core/skills.ts`; aquí vive solo dónde caen:
+ *
+ * - **De serie**: `<raíz del paquete>/skills/`. La raíz se BUSCA hacia arriba
+ *   (`agent/raizDelPaquete.ts`) en vez de contarse con `..`: contarlos ataba este fichero a
+ *   su profundidad, y moverlo de carpeta dejaba el catálogo vacío sin un error que leer. Se
+ *   resuelve contra ESTE módulo y no contra el cwd, que en la v1 es el proyecto del cliente.
+ * - **Global**: `~/.xonecode/skills/`.
+ * - **Del proyecto**: `<raiz>/.xonecode/skills/`.
+ *
+ * Las dos del usuario heredan de `.xonecode/` las dos protecciones que aquí importan: está
+ * denegada entera al agente (`permisosDe`) y **no sube nunca** a CloudStudio. Una skill es
+ * configuración de la herramienta, no del proyecto XOne.
+ *
+ * Y el agente NO las lee por esa ruta: las ve montadas en `/skills/<nombre>/`
+ * (`proyecto.ts#backendConSkills`), que es de solo lectura para él.
+ */
+export declare const RAIZ_SKILLS: string;
+/** La carpeta de skills de una raíz cualquiera. */
+export declare function rutaDeSkills(base: string): string;
+/** La global. `homedir()` en el momento de la llamada, como el resto del repo: cachearla en
+ *  una constante de módulo la congelaría para los tests que la cambian. */
+export declare function rutaGlobalDeSkills(): string;
+/** Estimación de coste. Se reexporta con el nombre viejo: lo usan los evals. */
+export declare const tokensDe: (texto: string) => number;
+/**
+ * Lee una carpeta de skills.
+ *
+ * Una que no se puede leer o que no valida NO tumba la carga: se salta, se apunta el motivo
+ * y las demás siguen — la misma postura que `leerCarpetaDeAgentes` con un `.md` a medio
+ * escribir, y la que evita que una skill rota deje la consola sin ninguna.
+ *
+ * Y el nombre NO se valida aquí: rechazar al leer haría desaparecer una skill que funciona.
+ * Se valida al GUARDAR, que es el único momento con alguien delante para arreglarlo — la
+ * misma regla, y por el mismo motivo, que la del nombre de un subagente.
+ */
+export declare function leerCarpetaDeSkills(carpeta: string, origen: OrigenDeSkill): LecturaDeSkills;
+/**
+ * Todas las skills en vigor, fundidas por nombre con el proyecto ganando.
+ *
+ * `raiz` ausente = no hay proyecto abierto, y entonces las del proyecto no existen. Es un
+ * caso normal —el vestíbulo— y no un hueco: `ausente ≠ vacío` no aplica aquí porque lo que
+ * falta es la CARPETA, no el dato.
+ */
+export declare function cargarSkills(raiz?: string): LecturaDeSkills;
+/** Dónde vive cada skill en el disco, para montarla. Solo las del USUARIO: las de serie ya
+ *  las cubre la raíz `/skills/` entera. */
+export interface Montaje {
+    nombre: string;
+    dir: string;
+}
+/**
+ * Las carpetas de las skills del USUARIO, para que `backendConSkills` las cuelgue una a una.
+ *
+ * Una a una y no una raíz más porque son DOS carpetas (la global y la del proyecto) que
+ * tienen que verse como UNA sola ruta virtual, `/skills/`: el subagente declara `skills:
+ * [mi-skill]` y eso se traduce a `/skills/mi-skill/` sin saber de dónde salió. Y porque el
+ * proyecto gana sobre el global, que es lo que `cargarSkills` ya decidió — aquí solo se
+ * respeta el resultado.
+ */
+export declare function skillsMontables(raiz?: string): Montaje[];
+/**
+ * Las CARPETAS que contienen skills, para un motor EXTERNO que descubre por directorio.
+ *
+ * **Por qué existe, y por qué no vale `skillsMontables`.** Aquélla devuelve una entrada por
+ * SKILL, que es lo que necesita nuestro `CompositeBackend` para colgar cada una de
+ * `/skills/<nombre>/`. Un motor externo no ve esa ruta virtual —corre en otro proceso y lee
+ * el disco— y descubre por CARPETA CONTENEDORA: opencode con `skills.paths` de su
+ * configuración, Claude Code con `additionalDirectories`. Son dos preguntas distintas y
+ * confundirlas da una lista de rutas que el motor descarta en silencio.
+ *
+ * **Solo las que EXISTEN.** Una ruta que no está es una entrada de configuración que el motor
+ * tiene que descartar por su cuenta, y cómo la descarte no lo decidimos nosotros — puede ser
+ * un aviso, puede ser un fallo de arranque. La carpeta global está vacía en una máquina que
+ * nunca guardó una skill propia, así que este caso es el normal y no el raro.
+ *
+ * **Y no se pasa por el proyecto abierto sin más**: la del proyecto cuelga de su `.xonecode/`,
+ * que es carpeta DENEGADA para los motores externos por todas las demás vías. Entra aquí
+ * porque el motor la carga ÉL al arrancar, no por una tool, que es la misma distinción que
+ * hace que `/skills/` sea de solo lectura para el agente interno.
+ *
+ * El orden es el de la precedencia de `cargarSkills` —serie, global, proyecto— para que un
+ * motor que resuelva un nombre repetido quedándose con el último coincida con lo que ve el
+ * agente interno.
+ */
+export declare function carpetasDeSkillsParaElMotor(opciones?: {
+    casa?: string;
+    raiz?: string;
+}): string[];
+/**
+ * TODAS las skills con su carpeta REAL, las de serie incluidas, con la precedencia de siempre.
+ *
+ * No es lo mismo que `skillsMontables`, y confundirlas costó un turno entero: aquélla contesta
+ * «qué carpetas hay que colgar de `/skills/` UNA A UNA», y las de serie no están ahí porque su
+ * raíz se cuelga ENTERA en `backendConSkills`. Para el backend da igual; para quien necesita la
+ * ruta de verdad de una skill —una shell, que no ve rutas virtuales— significaba que las nueve
+ * de serie no existían. Medido: el agente recibió un PATH sin sus scripts, probó el nombre a
+ * secas, falló, y acabó haciendo `find /` por el disco entero.
+ *
+ * El orden es el de la precedencia (`cargarSkills`): serie, luego global, luego proyecto, y el
+ * último gana. Una skill del proyecto que se llame igual que una de serie tapa a la de serie
+ * también aquí, que es lo que el agente ve por `/skills/`.
+ */
+export declare function skillsConRuta(raiz?: string): Montaje[];
+/**
+ * Escribe una skill del usuario. Devuelve el motivo si NO se escribió, nunca lanza.
+ *
+ * Tres negativas, y ninguna es de forma:
+ *
+ * - **Una de serie no se edita**: vive dentro del paquete instalado, así que el siguiente
+ *   `npm install` se llevaría el cambio sin decir nada. La consola ofrece copiarla.
+ * - **Un destino que existe es un NO**, venga de donde venga —de serie, global o del
+ *   proyecto—: es el motivo honesto y cubre los tres. Sin esto, crear una skill llamada
+ *   como una nuestra la tapaba en silencio, que es el agujero que el alta de subagentes ya
+ *   pagó.
+ * - **Y renombrar es `renameSync` y LUEGO escribir**, nunca escribir y luego borrar: un
+ *   fallo entre los dos pasos deja UNA carpeta y no dos con las mismas instrucciones.
+ */
+export declare function guardarSkill(base: string, skill: Skill, renombrandoDe?: string): {
+    ok: true;
+} | {
+    error: string;
+};
+/** Borra una skill del usuario. `false` = no estaba. Una de serie no llega aquí: la corta
+ *  el servidor, que es donde vive la guarda — esconder el icono es presentación. */
+export declare function borrarSkill(base: string, nombre: string): boolean;
+/** ¿La trae xonecode? Se pregunta al DISCO y no a una lista escrita a mano: la lista sería
+ *  un segundo sitio que mantener, y el día que divergiera nadie se enteraría. */
+export declare function esDeSerie(nombre: string): boolean;
+/**
+ * El catálogo que ve el AGENTE: las tres raíces, fundidas.
+ *
+ * **No cachea.** La versión anterior sí lo hacía —eran seis ficheros del paquete que no
+ * cambian a mitad de turno— y con las del usuario dentro eso dejó de ser cierto: se guarda
+ * una skill desde Ajustes con la consola abierta, y una lista congelada dentro de este objeto
+ * la dejaría fuera incluso de la siguiente construcción. Es la misma postura que `cargarAgentes`.
+ *
+ * **Lo que esto NO arregla**: construir el agente ocurre al abrir la sesión y en `/modelo`
+ * (`turnoReal.ts#construir`), no en cada turno, así que la skill nueva sigue sin alcanzar a la
+ * sesión que ya está abierta. Quitar la caché es condición necesaria y no suficiente; el
+ * agujero es heredado y está anotado en CLAUDE.md.
+ *
+ * `raiz` ausente = sin proyecto: solo las de serie y las globales.
+ */
+export declare class SkillsEnDisco implements SkillsPort {
+    private readonly raiz?;
+    constructor(raiz?: string | undefined);
+    catalogo(): SkillInfo[];
+    cargar(nombre: string): string;
+}
+/**
+ * Instala una skill desde un `.zip`. Devuelve el motivo si no se instaló, nunca lanza.
+ *
+ * El reparto: **la REGLA de qué se acepta vive en `core/zipDeSkill.ts`** —pura y probada sin
+ * un fichero delante— y aquí solo está lo que toca el disco. Es el mismo reparto que
+ * `core/agentes.ts` con `agentesEnDisco.ts`, y por lo mismo: la parte que decide si una ruta
+ * del zip puede escribirse es justo la que no puede depender de tener un zip a mano.
+ *
+ * Tres cosas que no son de forma:
+ *
+ * - **Se descomprime ENTERO en memoria y se comprueba ANTES de escribir nada.** Escribir
+ *   según se descomprime dejaría media skill en disco cuando la entrada 40 resulta ser un
+ *   `../`: un fallo a medias es peor que un no.
+ * - **El destino se comprueba con las MISMAS dos reglas que `guardarSkill`** —un nombre de
+ *   serie es un NO, un destino que existe es un NO—, porque instalar es otra forma de dar de
+ *   alta y un segundo sitio donde decidir eso es donde uno de los dos se queda sin la regla.
+ * - **Y cada ruta se vuelve a mirar al escribir**, aunque el plan ya la haya aceptado: es la
+ *   disciplina de `escrituraExterna.ts` —las guardas se REAPLICAN, no se asumen— y aquí
+ *   cuesta una llamada.
+ */
+export declare function instalarSkillDesdeZip(base: string, zip: Uint8Array, nombreDelFichero: string): {
+    ok: true;
+    nombre: string;
+} | {
+    error: string;
+};