xonecode 0.38.41 → 0.39.2

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

@@ -0,0 +1,225 @@
+/** Las tools de fichero que monta deepagents sobre el backend. */
+export declare const TOOLS_LECTURA: readonly ["ls", "read_file", "glob", "grep"];
+export declare const TOOLS_ESCRITURA: readonly ["write_file", "edit_file"];
+/**
+ * Lo que estas tres funciones MIRAN de verdad, y nada más.
+ *
+ * Antes pedían un `Perfil` entero. Desde que los subagentes son ficheros
+ * (`core/agentes.ts`) quien llega aquí es un `Agente`, y las dos formas comparten
+ * exactamente estos dos campos: el nombre para poder decirlo en la petición de aprobación,
+ * y si escribe o no. Pedir el tipo grande obligaría a convertir un `Agente` en un `Perfil`
+ * —o sea a inventarle campos— solo para preguntarle si puede escribir.
+ */
+export interface QuienDecidePermisos {
+    nombre: string;
+    soloLectura: boolean;
+    /**
+     * Las carpetas del PROYECTO donde este agente sí puede escribir, aunque sea de solo
+     * lectura. Ausente o vacía = ninguna, que es como se ha comportado siempre.
+     *
+     * Nace del documentador: su trabajo es dejar un manual en `doc/`, y sin esto la única
+     * forma de dárselo era quitarle el `soloLectura` — o sea, dejarle tocar el código
+     * entero para que pudiera escribir un `.md`. Esto parte esas dos cosas: puede escribir
+     * DONDE se le diga y en ningún otro sitio.
+     *
+     * Son rutas VIRTUALES del backend (`/doc/`), no de la máquina, y se comparan por
+     * prefijo de SEGMENTO: `/doc` no abre `/documentos`.
+     */
+    escribeEn?: readonly string[];
+}
+/**
+ * ¿Cae `ruta` dentro de `carpeta`? Por SEGMENTO y no por texto.
+ *
+ * `"/documentos/x".startsWith("/doc")` es cierto y sería un agujero: conceder `/doc`
+ * abriría cualquier carpeta que empiece igual. Se normaliza la carpeta con su barra final
+ * y se admite además la ruta exacta, para que `escribeEn: ["/doc"]` y `["/doc/"]` digan
+ * lo mismo — quien escribe un `.md` no tiene por qué saber cuál de las dos esperamos.
+ */
+export declare function dentroDeCarpeta(ruta: string, carpeta: string): boolean;
+/** Lo que estructuralmente da igual quién seas: nunca se lee ni se escribe. */
+export declare const DENEGADO_SIEMPRE: ({
+    operations: readonly ["read", "write"];
+    paths: string[];
+    mode: "deny";
+} | {
+    operations: readonly ["write"];
+    paths: string[];
+    mode: "deny";
+})[];
+/**
+ * Los permisos de un perfil. **Nunca los escribas a mano.**
+ *
+ * `SubAgent.permissions` REEMPLAZA los del padre, no los fusiona. Así que cada perfil que
+ * declare permisos propios tiene que traerse las denegaciones base consigo o las pierde —
+ * y perder la de `.env` significa que un especialista «de solo lectura» puede leer las
+ * claves del usuario. Esta función es lo único que evita ese olvido.
+ */
+export declare function permisosDe(perfil: QuienDecidePermisos): ({
+    operations: readonly ["read", "write"];
+    paths: string[];
+    mode: "deny";
+} | {
+    operations: readonly ["write"];
+    paths: string[];
+    mode: "deny";
+} | {
+    operations: readonly ["write"];
+    paths: string[];
+    mode: "allow";
+})[];
+/**
+ * Las tools de fichero de un agente con EJECUCIÓN.
+ *
+ * `read_file` tiene que estar siempre (lo exige el middleware). Lo que NO está son
+ * `write_file` y `edit_file`: no porque no pueda escribir —con una shell puede, y fingir lo
+ * contrario sería peor que no decir nada— sino para que el camino normal de tocar el
+ * proyecto siga siendo el que pasa por la aprobación y por el diff. Quien escribe el proyecto
+ * es `developer-xone`; éste conduce un aparato.
+ */
+export declare const TOOLS_CON_EJECUCION: readonly ["read_file", "ls", "glob", "grep", "execute"];
+/** Lo que este módulo mira para decidir si un agente ejecuta. */
+export interface QuienDecideEjecucion extends QuienDecidePermisos {
+    ejecucion?: boolean;
+    motor?: string;
+}
+/**
+ * Si a este agente le toca la shell.
+ *
+ * Dos condiciones, y la segunda no es una formalidad: en los tres motores EXTERNOS la shell
+ * está cerrada a propósito (`Bash` denegada, la tool retirada, el sandbox `read-only`) y el
+ * hijo corre en otro proceso donde este campo no manda nada. Honrarlo ahí sería prometer una
+ * capacidad que no llega; ignorarlo en silencio, esconder que no llega. Se decide aquí, en un
+ * sitio, y la ventana de Ajustes lo cuenta.
+ */
+export declare function puedeEjecutar(perfil: QuienDecideEjecucion): boolean;
+/**
+ * Cuántas llamadas al modelo puede gastar ESTE perfil en un encargo.
+ *
+ * Se decide por `ejecucion` y **no por el nombre del agente**: `device-controller` es quien
+ * lo tiene hoy, pero una regla que nombrara a un agente se queda escrita y muerta el día que
+ * lo renombren — ya pasó con `planner`. Lo que justifica el presupuesto largo es el trabajo,
+ * no quién lo hace: el que conduce un aparato avanza en un bucle de acto→observa, y el que
+ * lee y contesta no.
+ *
+ * Pura y exportada por el patrón de fallo de siempre: compuesta dentro de `construirAgente`
+ * —que todos sus tests doblan— «el conductor lleva otro presupuesto» quedaría escrito y sin
+ * probar, y el síntoma sería el de ahora, con todo en verde.
+ */
+export declare function presupuestoDeLlamadas(perfil: QuienDecideEjecucion): number;
+/**
+ * Con qué backend y con qué reglas se le montan las tools de fichero a un especialista.
+ *
+ * Existe como función PURA y exportada por el patrón de fallo de este repo: compuesto dentro
+ * de `construirAgente` —que todos sus tests doblan— «este agente lleva shell y aquél no»
+ * quedaría escrito y sin probar, y el síntoma sería el peor de todos: todo en verde y un
+ * especialista corriente con una shell, o el de dispositivos sin ella y sin error que leer.
+ *
+ * **Y `permissions` NO se pasa con un backend ejecutable.** No es una elección: deepagents
+ * LANZA (`ConfigurationError`) si se combinan, porque «los comandos alcanzan cualquier ruta
+ * independientemente de las reglas de ruta». O sea que la biblioteca se niega a sostener una
+ * barrera que no sería verdad — y esa negativa es la razón por la que esto se concede a UN
+ * agente y se declara en su fichero.
+ */
+export declare function montajeDeFicheros<B>(perfil: QuienDecideEjecucion, backends: {
+    normal: B;
+    conShell?: B;
+}): {
+    backend: B;
+    permissions?: ReturnType<typeof permisosDe>;
+    tools?: typeof TOOLS_CON_EJECUCION;
+};
+/**
+ * Barrera de lectura para tools propias.
+ *
+ * `FilesystemMiddleware` aplica `permisosDe()` a sus seis herramientas, pero
+ * una tool de LangChain añadida por xonecode no pasa por ese middleware. Las
+ * rutas protegidas se concentran aquí para que esas tools no abran por accidente
+ * `.env`, `.git` ni la carpeta interna del proyecto.
+ */
+export declare function puedeLeerRuta(ruta: string): boolean;
+/**
+ * ¿Puede ESTE agente escribir en ESTA ruta? El espejo de `permisosDe`, como predicado.
+ *
+ * Existe porque **una tool propia no pasa por el middleware de permisos** —ya está dicho de
+ * `regex_search` y de `xone_navegacion`, que reaplican `puedeLeerRuta` a mano—, y una tool
+ * que escriba tiene el mismo deber con más consecuencias: sin esto, `copiar_artefacto`
+ * sería la puerta trasera por la que un agente de solo lectura mete ficheros en el
+ * proyecto, que es exactamente lo que `permisosDe` existe para impedir.
+ *
+ * Se mantiene en el MISMO fichero y al lado de `permisosDe` a propósito: son dos formas de
+ * la misma regla, y separarlas es cómo una se queda vieja. Si algún día divergen, lo que
+ * hay que hacer es derivar una de la otra, no añadir una tercera.
+ */
+export declare function puedeEscribirRuta(perfil: QuienDecidePermisos, ruta: string): boolean;
+/**
+ * Las tools de fichero que le corresponden a un perfil.
+ *
+ * **No se le pasa a `SubAgent.tools`**: ese campo es `StructuredTool[]` —objetos, para
+ * tools propias— y darle nombres deja al especialista sin capacidades. Las de fichero las
+ * monta el `FilesystemMiddleware` desde el backend, y el solo-lectura se impone con
+ * `permisosDe()`, que la librería aplica sobre las seis.
+ *
+ * Esta función se conserva porque describe la intención y la comprueban los tests. El día
+ * que se quiera OCULTAR las de escritura (en vez de denegarlas), el sitio es la opción
+ * `tools` del `FilesystemMiddleware` — y ahí `read_file` es obligatorio en la lista.
+ */
+export declare function toolsDe(perfil: QuienDecidePermisos): string[];
+/** Texto de la petición de aprobación, por tool. */
+export declare const TEXTO_HITL: Record<string, string>;
+/**
+ * El HITL de un perfil: **sobre las tools de FICHERO**, no sobre las de MCP.
+ *
+ * Con MCP las escrituras iban a CloudStudio y el disco local estaba denegado entero; ahora
+ * las escrituras SON el mecanismo. Si esto no se mueve, la aprobación humana desaparece en
+ * silencio y la promesa de que «las escrituras se aprueban» se queda escrita y falsa.
+ *
+ * `edit` no se ofrece como decisión: no hay interfaz para editar los argumentos antes de
+ * aprobar, así que anunciarla sería mentirle al modelo.
+ */
+export declare function hitlDe(perfil: QuienDecidePermisos): Record<string, ConfigDeInterrupt>;
+/**
+ * ¿Se para el turno a preguntar por ESTA escritura?
+ *
+ * El predicado `when` de `InterruptOnConfig` (leído en `langchain/agents/middleware/hitl`:
+ * «Returns `true` to interrupt or `false` to auto-approve the tool call»), y aquí existe
+ * para una sola cosa: **una escritura que el backend va a rechazar de todas formas no puede
+ * sacar un modal de aprobación.** Pasaba, y medido: pedir un artefacto en `/artifacts/`
+ * enseñaba el diff entero con Aprobar y Rechazar, y aprobarlo no escribía nada —
+ * `sinArtefactosEnElProyecto` lo rechaza después—. Un modal cuyo único final posible es un
+ * rechazo enseña a aprobar sin mirar, que es exactamente cómo se rompe la aprobación el día
+ * que importa.
+ *
+ * **Esto NO relaja la aprobación, y esa es la parte delicada.** No se salta la pregunta para
+ * escribir: se salta para NO escribir. La condición es la MISMA función que usa la guarda del
+ * backend —`artefactoFueraDeSitio`, sobre la misma cadena—, así que las dos no pueden
+ * discrepar; si discreparan, una escritura al proyecto pasaría sin que nadie la aprobara, que
+ * es el único fallo abierto posible por aquí. `perfiles.test.ts` lo ata: para cada ruta,
+ * saltarse la pregunta implica que la guarda la rechaza.
+ *
+ * Lo que pasa después es lo que se busca: la tool corre, el backend devuelve su `{error}` con
+ * la ruta buena, y el modelo reintenta en `/artefactos/`.
+ *
+ * **Y un SEGUNDO motivo, que es de coherencia y no de relajación**: tampoco se pregunta por lo
+ * que NO ES EL PROYECTO —`/artefactos/` y `/planes/`—. No es una excepción nueva: un perfil de
+ * SOLO LECTURA ya escribe esas dos rutas sin aprobación ninguna, porque `hitlDe` le devuelve
+ * `{}` y sus `permissions` lo confinan exactamente ahí. O sea que la misma ruta no se aprobaba
+ * para el analista y sí para el desarrollador, y eso no es una barrera: es una incoherencia que
+ * se paga cara — medido, el desarrollador fue a marcar como hecha una tarea de un plan, salió
+ * un modal, se rechazó, y el plan se quedó viejo en silencio. En una tarea de fondo no hay
+ * nadie que pulse, así que el plan NUNCA se marcaría.
+ *
+ * Ninguna de las dos rutas es la app del cliente: no entran en el commit del turno, no van a
+ * git y no suben a CloudStudio. Lo que sigue intacto es lo único que importa: **por un fichero
+ * del PROYECTO siempre se pregunta**, y el test lo comprueba ruta a ruta.
+ */
+export declare function seDetieneEn(peticion: unknown): boolean;
+/**
+ * La forma del `interruptOn` de una tool, declarada aquí porque deepagents la reenvía tal
+ * cual a `humanInTheLoopMiddleware` sin tipar el `when` en su propia interfaz.
+ */
+export interface ConfigDeInterrupt {
+    allowedDecisions: string[];
+    description: string;
+    /** Ver `seDetieneEn`. */
+    when: (peticion: unknown) => boolean;
+}